monkey/docs/content/development/adding-system-info-collectors.md

title	date	draft	tags	weight
Adding System Info Collectors	2020-06-09T11:03:42+03:00	false	contribute	80

What's this?

This guide will show you how to create a new System Info Collector for the Infection Monkey. System Info Collectors are modules which each Monkey runs, that collect specific information and sends it back to the Island as part of the System Info Telemetry.

Do I need a new System Info Controller?

If all you want is to execute a shell command, then there's no need to add a new collector - just configure the required commands in the Monkey Island configuration in the PBA section! Also, if there is a relevant collector and you only need to add more information to it, expand the existing one. Otherwise, you must add a new Collector.

How to add a new System Info Collector

Monkey side

Framework

1. Create your new collector in the following directory: monkey/infection_monkey/system_info/collectors by first creating a new file with the name of your collector.
2. In that file, create a class that inherits from the SystemInfoCollector class:

from infection_monkey.system_info.system_info_collector import SystemInfoCollector

class MyNewCollector(SystemInfoCollector):

3. Set the Collector name in the C'tor, like so:

class MyNewCollector(SystemInfoCollector):
    def __init__(self):
        super(MyNewCollector, self).__init__(name="MyNewCollector")

Implementation

Override the collect method with your own implementation. See the EnvironmentCollector.py Collector for reference. You can log during collection as well.

Configuration

Add the new collector to infection_monkey/config.py

Island side

Configuration

definitions

You'll need to add your Collector to the config_schema.py file, under definitions/system_info_collectors_classes/anyOf, like so:

"system_info_collectors_classes": {
    "title": "System Information Collectors",
    "type": "string",
    "anyOf": [
        {
            "type": "string",
            "enum": [
                "EnvironmentCollector"
            ],
            "title": "Which Environment this machine is on (on prem/cloud)",
            "attack_techniques": []
        },
        {                               <=================================
            "type": "string",           <=================================
            "enum": [                   <=================================
                "MyNewCollector"        <=================================
            ],                          <=================================
            "title": "My new title",    <=================================
            "attack_techniques": []     <=================================
        },
    ],
},

properties

Also, you can add the Collector to be used by default by adding it to the default key under properties/monkey/system_info/system_info_collectors_classes:

"system_info_collectors_classes": {
    "title": "System info collectors",
    "type": "array",
    "uniqueItems": True,
    "items": {
        "$ref": "#/definitions/system_info_collectors_classes"
    },
    "default": [
        "EnvironmentCollector",
        "MyNewCollector"    <=================================
    ],
    "description": "Determines which system information collectors will collect information."
},

Telemetry processing

1. Add a process function under monkey_island/cc/telemetry/processing/system_info_collectors/{DATA_NAME_HERE}.py. The function should parse the collector's result. See processing/system_info_collectors/environment.py for example.

2. Add that function to the dispatcher - monkey_island/cc/services/telemetry/processing/system_info_collectors/system_info_telemetry_dispatcher.py.