From f3a2bd68ec73a70fb8af42a6da96d19b73393923 Mon Sep 17 00:00:00 2001 From: Shay Nehmad Date: Tue, 14 Jul 2020 10:42:35 +0300 Subject: [PATCH 1/5] Migrated and updated docs from our wiki to the new docs site Added tags to pages --- .../development/add-zero-trust-test.md | 26 +++++ docs/content/development/adding-exploits.md | 2 + .../development/adding-post-breach-actions.md | 72 ++++++++++++- .../adding-system-info-collectors.md | 101 +++++++++++++++++- .../development/contribute-documentation.md | 1 + .../setup-development-environment.md | 3 +- docs/content/reference/_index.md | 14 +++ .../reference/exploiters/ElasticGroovy.md | 12 +++ docs/content/reference/exploiters/Hadoop.md | 8 ++ docs/content/reference/exploiters/MS08-067.md | 10 ++ docs/content/reference/exploiters/MsSQL.md | 8 ++ docs/content/reference/exploiters/SMBExec.md | 8 ++ docs/content/reference/exploiters/SSHExec.md | 8 ++ docs/content/reference/exploiters/Sambacry.md | 8 ++ docs/content/reference/exploiters/Struts2.md | 8 ++ docs/content/reference/exploiters/VSFTPD.md | 8 ++ docs/content/reference/exploiters/WMIExec.md | 8 ++ docs/content/reference/exploiters/WebLogic.md | 8 ++ docs/content/reference/exploiters/_index.md | 16 +++ .../reference/exploiters/shellshock.md | 10 ++ .../reference/operating_systems_support.md | 64 +++++++++++ docs/content/reference/scanners/_index.md | 51 +++++++++ .../{usage => setup}/accounts-and-security.md | 0 docs/content/setup/debian.md | 2 +- docs/content/setup/docker.md | 2 +- 25 files changed, 453 insertions(+), 5 deletions(-) create mode 100644 docs/content/development/add-zero-trust-test.md create mode 100644 docs/content/reference/_index.md create mode 100644 docs/content/reference/exploiters/ElasticGroovy.md create mode 100644 docs/content/reference/exploiters/Hadoop.md create mode 100644 docs/content/reference/exploiters/MS08-067.md create mode 100644 docs/content/reference/exploiters/MsSQL.md create mode 100644 docs/content/reference/exploiters/SMBExec.md create mode 100644 docs/content/reference/exploiters/SSHExec.md create mode 100644 docs/content/reference/exploiters/Sambacry.md create mode 100644 docs/content/reference/exploiters/Struts2.md create mode 100644 docs/content/reference/exploiters/VSFTPD.md create mode 100644 docs/content/reference/exploiters/WMIExec.md create mode 100644 docs/content/reference/exploiters/WebLogic.md create mode 100644 docs/content/reference/exploiters/_index.md create mode 100644 docs/content/reference/exploiters/shellshock.md create mode 100644 docs/content/reference/operating_systems_support.md create mode 100644 docs/content/reference/scanners/_index.md rename docs/content/{usage => setup}/accounts-and-security.md (100%) diff --git a/docs/content/development/add-zero-trust-test.md b/docs/content/development/add-zero-trust-test.md new file mode 100644 index 000000000..d43dcacef --- /dev/null +++ b/docs/content/development/add-zero-trust-test.md @@ -0,0 +1,26 @@ +--- +title: "Adding Zero Trust Tests" +date: 2020-07-14T10:19:08+03:00 +draft: false +weight: 100 +--- + +## How to add a new Zero Trust test to the Monkey? + +Assuming the Monkey agent is already sending the relevant telemetry, you'll need to add the test in two places. + +### `zero_trust_consts.py` + +In the file `/monkey/common/data/zero_trust_consts.py`, + +1. Add the test name to the TESTS set +2. Add a relevant recommendation if exists +3. Add the test to the TESTS_MAP dict. Make sure that all statuses (except `STATUS_UNEXECUTED`) have finding explanations. + +### `telemetry/processing.py` + +Find the relevant telemetry type you wish to test the finding in. This can be found in `/monkey/monkey_island/cc/services/telemetry/processing.py`. In the relevant `process_*_telemetry` function, add your Zero Trust testing code. Please put the zero trust tests under the `/monkey/monkey_island/cc/services/telemetry/zero_trust_tests` directory. There you can find examples of existing tests as well, so you'll know pretty much what you need to write. + +## How to test the new Zero Trust test I've implemented? + +Test ALL possible finding statuses you've defined in a fake network. Observe the events as well and see they were formatted correctly. If there's an algorithmic part to your Zero Trust test, please cover it using a Unit Test. diff --git a/docs/content/development/adding-exploits.md b/docs/content/development/adding-exploits.md index 3e434773f..d6af6814c 100644 --- a/docs/content/development/adding-exploits.md +++ b/docs/content/development/adding-exploits.md @@ -2,4 +2,6 @@ title: "Adding Exploits" date: 2020-06-08T19:53:00+03:00 draft: true +tags: ["contribute"] +weight: 50 --- diff --git a/docs/content/development/adding-post-breach-actions.md b/docs/content/development/adding-post-breach-actions.md index 17da583c2..419cbf641 100644 --- a/docs/content/development/adding-post-breach-actions.md +++ b/docs/content/development/adding-post-breach-actions.md @@ -1,6 +1,76 @@ --- title: "Adding Post Breach Actions" date: 2020-06-08T19:53:13+03:00 -draft: true +draft: false +tags: ["contribute"] +weight: 90 --- +## What's this? + +This guide will show you how to create a new _Post Breach action_ for the Infection Monkey. _Post Breach actions_ are "extra" actions that the Monkey can perform on the victim machines after it propagated to them. + +## Do I need a new PBA? + +If all you want is to execute shell commands, then there's no need to add a new PBA - just configure the required commands in the Monkey Island configuration! If you think that those specific commands have reuse value in all deployments and not just your own, you can add a new PBA. If you need to run actual Python code, you must add a new PBA. + +## How to add a new PBA + +### Monkey side + +#### Framework + +1. Create your new action in the following directory: `monkey/infection_monkey/post_breach/actions` by first creating a new file with the name of your action. +2. In that file, create a class that inherits from the `PBA` class: + +```python +from infection_monkey.post_breach.pba import PBA + +class MyNewPba(PBA): +``` + +3. Set the action name in the C'tor, like so: + +```python +class MyNewPba(PBA): + def __init__(self): + super(MyNewPba, self).__init__(name="MyNewPba") +``` + +#### Implementation + +If your PBA consists only of simple shell commands, you can reuse the generic PBA by passing the commands into the constructor. See the `add_user.py` PBA for reference. + +Otherwise, you'll need to override the `run` method with your own implementation. See the `communicate_as_new_user.py` PBA for reference. Make sure to send the relevant PostBreachTelem upon success/failure. You can log during the PBA as well. + +### Island side + +#### Configuration + +You'll need to add your PBA to the `config_schema.py` file, under `post_breach_acts`, like so: + +```json +"post_breach_acts": { + "title": "Post breach actions", + "type": "string", + "anyOf": [ + # ... + { + "type": "string", + "enum": [ + "MyNewPba" + ], + "title": "My new PBA", + "attack_techniques": [] + }, + ], + }, +``` + +Now you can choose your PBA when configuring the Monkey on the Monkey island: + +![PBA in configuration](https://i.imgur.com/9PrcWr0.png) + +#### Telemetry processing + +If you wish to process your Post Breach action telemetry (for example, to analyze it for report data), add a processing function to the `POST_BREACH_TELEMETRY_PROCESSING_FUNCS` which can be found at `monkey/monkey_island/cc/services/telemetry/processing/post_breach.py`. You can look at the `process_communicate_as_new_user_telemetry` method as an example. diff --git a/docs/content/development/adding-system-info-collectors.md b/docs/content/development/adding-system-info-collectors.md index 9bc404d7c..c6c279a0a 100644 --- a/docs/content/development/adding-system-info-collectors.md +++ b/docs/content/development/adding-system-info-collectors.md @@ -1,6 +1,105 @@ --- title: "Adding System Info Collectors" date: 2020-06-09T11:03:42+03:00 -draft: true +draft: false +tags: ["contribute"] +weight: 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: + +```py +from infection_monkey.system_info.system_info_collector import SystemInfoCollector + +class MyNewCollector(SystemInfoCollector): +``` + +3. Set the Collector name in the C'tor, like so: + +```py +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: + +```json +"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`: + +```json +"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`. diff --git a/docs/content/development/contribute-documentation.md b/docs/content/development/contribute-documentation.md index 9e6dc890e..5d6913edb 100644 --- a/docs/content/development/contribute-documentation.md +++ b/docs/content/development/contribute-documentation.md @@ -2,6 +2,7 @@ title: "Contribute Documentation" date: 2020-06-17T17:31:54+03:00 draft: false +weight: 1 tags: ["contribute"] --- diff --git a/docs/content/development/setup-development-environment.md b/docs/content/development/setup-development-environment.md index ff0d6445f..b2d0b7f1e 100644 --- a/docs/content/development/setup-development-environment.md +++ b/docs/content/development/setup-development-environment.md @@ -1,7 +1,8 @@ --- -title: "Setting up a development environment" +title: "Development setup" date: 2020-06-08T19:53:00+03:00 draft: false +weight: 5 tags: ["contribute"] --- diff --git a/docs/content/reference/_index.md b/docs/content/reference/_index.md new file mode 100644 index 000000000..b4aad3921 --- /dev/null +++ b/docs/content/reference/_index.md @@ -0,0 +1,14 @@ ++++ +title = "Reference" +date = 2020-05-26T20:55:04+03:00 +weight = 30 +chapter = true +pre = ' ' +tags = ["reference"] ++++ + +# Reference + +Your source of all Monkey information. + +{{% children %}} diff --git a/docs/content/reference/exploiters/ElasticGroovy.md b/docs/content/reference/exploiters/ElasticGroovy.md new file mode 100644 index 000000000..7325ccb86 --- /dev/null +++ b/docs/content/reference/exploiters/ElasticGroovy.md @@ -0,0 +1,12 @@ +--- +title: "ElasticGroovy" +date: 2020-07-14T08:41:40+03:00 +draft: false +tags: ["exploit", "windows", "linux"] +--- + +CVE-2015-1427. + +> The Groovy scripting engine in Elasticsearch before 1.3.8 and 1.4.x before 1.4.3 allows remote attackers to bypass the sandbox protection mechanism and execute arbitrary shell commands via a crafted script. + +Logic is based on [Metasploit module](https://github.com/rapid7/metasploit-framework/blob/12198a088132f047e0a86724bc5ebba92a73ac66/modules/exploits/multi/elasticsearch/search_groovy_script.rb). diff --git a/docs/content/reference/exploiters/Hadoop.md b/docs/content/reference/exploiters/Hadoop.md new file mode 100644 index 000000000..7d9de287b --- /dev/null +++ b/docs/content/reference/exploiters/Hadoop.md @@ -0,0 +1,8 @@ +--- +title: "Hadoop" +date: 2020-07-14T08:41:49+03:00 +draft: false +tags: ["exploit", "linux", "windows"] +--- + +Remote code execution on HADOOP server with YARN and default settings. Logic based on [this vulhub module](https://github.com/vulhub/vulhub/tree/master/hadoop/unauthorized-yarn). diff --git a/docs/content/reference/exploiters/MS08-067.md b/docs/content/reference/exploiters/MS08-067.md new file mode 100644 index 000000000..3f0c57cc3 --- /dev/null +++ b/docs/content/reference/exploiters/MS08-067.md @@ -0,0 +1,10 @@ +--- +title: "MS08 067" +date: 2020-07-14T08:42:54+03:00 +draft: false +tags: ["exploit", "windows"] +--- + +[MS08-067](https://docs.microsoft.com/en-us/security-updates/securitybulletins/2008/ms08-067) is a remote code execution vulnerability. + +This exploiter is unsafe. If an exploit attempt fails, this could also lead to a crash in Svchost.exe. If the crash in Svchost.exe occurs, the Server service will be affected. That might cause system crash due to the use of buffer overflow. It's therefore **not** enabled by default. diff --git a/docs/content/reference/exploiters/MsSQL.md b/docs/content/reference/exploiters/MsSQL.md new file mode 100644 index 000000000..2d664503b --- /dev/null +++ b/docs/content/reference/exploiters/MsSQL.md @@ -0,0 +1,8 @@ +--- +title: "MsSQL" +date: 2020-07-14T08:41:56+03:00 +draft: false +tags: ["exploit", "windows"] +--- + +The Monkey will try to brute force into MsSQL server and uses insecure configuration to execute commands on server. diff --git a/docs/content/reference/exploiters/SMBExec.md b/docs/content/reference/exploiters/SMBExec.md new file mode 100644 index 000000000..cccf0596d --- /dev/null +++ b/docs/content/reference/exploiters/SMBExec.md @@ -0,0 +1,8 @@ +--- +title: "SMBExec" +date: 2020-07-14T08:42:16+03:00 +draft: false +tags: ["exploit", "windows"] +--- + +Brute forces using credentials provided by user (see ["Configuration"](../usage/configuration)) and hashes gathered by Mimikatz. diff --git a/docs/content/reference/exploiters/SSHExec.md b/docs/content/reference/exploiters/SSHExec.md new file mode 100644 index 000000000..d90d311cb --- /dev/null +++ b/docs/content/reference/exploiters/SSHExec.md @@ -0,0 +1,8 @@ +--- +title: "SSHExec" +date: 2020-07-14T08:42:21+03:00 +draft: false +tags: ["exploit", "linux"] +--- + +Brute forces using credentials provided by user (see ["Configuration"](../usage/configuration))and SSH keys gathered from systems. diff --git a/docs/content/reference/exploiters/Sambacry.md b/docs/content/reference/exploiters/Sambacry.md new file mode 100644 index 000000000..1187d08ed --- /dev/null +++ b/docs/content/reference/exploiters/Sambacry.md @@ -0,0 +1,8 @@ +--- +title: "Sambacry" +date: 2020-07-14T08:42:02+03:00 +draft: false +tags: ["exploit", "linux"] +--- + +Bruteforces and searches for anonymous shares. Partially based on [the following implementation](https://github.com/CoreSecurity/impacket/blob/master/examples/sambaPipe.py) by CORE Security Technologies' impacket. diff --git a/docs/content/reference/exploiters/Struts2.md b/docs/content/reference/exploiters/Struts2.md new file mode 100644 index 000000000..a81f61575 --- /dev/null +++ b/docs/content/reference/exploiters/Struts2.md @@ -0,0 +1,8 @@ +--- +title: "Struts2" +date: 2020-07-14T08:42:30+03:00 +draft: false +tags: ["exploit", "linux", "windows"] +--- + +Exploits struts2 java web framework. CVE-2017-5638. Logic based on [VEX WOO's PoC](https://www.exploit-db.com/exploits/41570). diff --git a/docs/content/reference/exploiters/VSFTPD.md b/docs/content/reference/exploiters/VSFTPD.md new file mode 100644 index 000000000..ce5a6dcc3 --- /dev/null +++ b/docs/content/reference/exploiters/VSFTPD.md @@ -0,0 +1,8 @@ +--- +title: "VSFTPD" +date: 2020-07-14T08:42:39+03:00 +draft: false +tags: ["exploit", "linux"] +--- + +Exploits a malicious backdoor that was added to the VSFTPD download archive. Logic based on [this MetaSploit module](https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/unix/ftp/vsftpd_234_backdoor.rb). diff --git a/docs/content/reference/exploiters/WMIExec.md b/docs/content/reference/exploiters/WMIExec.md new file mode 100644 index 000000000..490c33fcf --- /dev/null +++ b/docs/content/reference/exploiters/WMIExec.md @@ -0,0 +1,8 @@ +--- +title: "WMIExec" +date: 2020-07-14T08:43:12+03:00 +draft: false +tags: ["exploit", "windows"] +--- + +Brute forces WMI (Windows Management Instrumentation) using credentials provided by user ((see ["Configuration"](../usage/configuration))) and hashes gathered by mimikatz. diff --git a/docs/content/reference/exploiters/WebLogic.md b/docs/content/reference/exploiters/WebLogic.md new file mode 100644 index 000000000..051fa4732 --- /dev/null +++ b/docs/content/reference/exploiters/WebLogic.md @@ -0,0 +1,8 @@ +--- +title: "WebLogic" +date: 2020-07-14T08:42:46+03:00 +draft: false +tags: ["exploit", "linux", "windows"] +--- + +Exploits CVE-2017-10271 and CVE-2019-2725 vulnerabilities on a vulnerable WebLogic server. diff --git a/docs/content/reference/exploiters/_index.md b/docs/content/reference/exploiters/_index.md new file mode 100644 index 000000000..4624081d8 --- /dev/null +++ b/docs/content/reference/exploiters/_index.md @@ -0,0 +1,16 @@ ++++ +title = "Exploiters" +date = 2020-05-26T20:55:04+03:00 +weight = 100 +chapter = true +pre = ' ' +tags = ["reference", "exploit"] ++++ + +# Exploiters + +Infection Monkey uses various RCE exploiters. Most of these, in our knowledge, pose no risk to performance or services on victim machines. This documentation serves as a quick introduction to the exploiters currently implemented and vulnerabilities used by them. + +{{% children %}} + +You can check out the Exploiters' implementation yourself [in the Monkey's GitHub repository](https://github.com/guardicore/monkey/tree/develop/monkey/infection_monkey/exploit). diff --git a/docs/content/reference/exploiters/shellshock.md b/docs/content/reference/exploiters/shellshock.md new file mode 100644 index 000000000..c220ae24f --- /dev/null +++ b/docs/content/reference/exploiters/shellshock.md @@ -0,0 +1,10 @@ +--- +title: "ShellShock" +date: 2020-07-14T08:41:32+03:00 +draft: false +tags: ["exploit", "linux"] +--- + +CVE-2014-6271, based on [logic in NCC group's GitHub](https://github.com/nccgroup/shocker/blob/master/shocker.py). + +> GNU Bash through 4.3 processes trailing strings after function definitions in the values of environment variables, which allows remote attackers to execute arbitrary code via a crafted environment, as demonstrated by vectors involving the ForceCommand feature in OpenSSH sshd, the mod_cgi and mod_cgid modules in the Apache HTTP Server, scripts executed by unspecified DHCP clients, and other situations in which setting the environment occurs across a privilege boundary from Bash execution, aka "ShellShock." diff --git a/docs/content/reference/operating_systems_support.md b/docs/content/reference/operating_systems_support.md new file mode 100644 index 000000000..0baf41eb7 --- /dev/null +++ b/docs/content/reference/operating_systems_support.md @@ -0,0 +1,64 @@ +--- +title: "Operating systems" +date: 2020-07-14T08:09:53+03:00 +draft: false +pre: ' ' +weight: 10 +tags: ["setup", "reference", "windows", "linux"] +--- + +The Infection Monkey project supports many popular OSes (but we can always do more). + +The Monkey itself (the agent) has been tested to run on the following operating systems (on x64 architecture) + +### Monkey support + +#### Linux + +Compatibility depends on GLIBC version (2.14+)[^1]. By default these distributions are supported: + +- Centos 7+ +- Debian 7+ +- Kali 2019+ +- Oracle 7+ +- Rhel 7+ +- Suse 12+ +- Ubuntu 14+ + +#### Windows + +- Windows 2012+ +- Windows 2012_R2+ +- Windows 7/Server 2008_R2 if [KB2999226](https://support.microsoft.com/en-us/help/2999226/update-for-universal-c-runtime-in-windows) is installed. +- Windows vista/Server 2008 should also work if the same update is installed, but this wasn't tested. + +### Island support + +**The Monkey Island (control server)** runs out of the box on: + +- Ubuntu 18.04 +- Debian 9 +- Windows Server 2012 +- Windows Server 2012 R2 +- Windows Server 2016 + +We provide a dockerfile from our [website](http://infectionmonkey.com/) that lets the Monkey Island run inside a container. + +### Old machine bootloader + +Some **Older machines** still get a partial compatibility as in they get exploited and reported, but monkey can't run on them. So instead of monkey, old machine bootloader(small c program) is ran, which reports some minor info like network interface configuration, GLIBC version, OS and so on. + +**Old machine bootloader** also has a GLIBC 2.14+ requirement for linux, because bootloader is included into pyinstaller bootloader which uses python3.7, which in turn requires GLIBC 2.14+. If you think partial support for older machines is important, don't hesitate to open a new issue about it. + +**Old machine bootloader** runs on machines with: + +- Centos 7+ +- Debian 7+ +- Kali 2019+ +- Oracle 7+ +- Rhel 7+ +- Suse 12+ +- Ubuntu 14+ +- **Windows XP/Server 2003+** + +[^1]: GLIBC >= 2.14 requirement comes from the fact that monkey is built using this GLIBC version and GLIBC is not backwards compatible. We are also limited to the oldest GLIBC version compatible with ptyhon3.7 diff --git a/docs/content/reference/scanners/_index.md b/docs/content/reference/scanners/_index.md new file mode 100644 index 000000000..25c2de099 --- /dev/null +++ b/docs/content/reference/scanners/_index.md @@ -0,0 +1,51 @@ +--- +title: "Scanners" +date: 2020-07-14T08:43:12+03:00 +draft: false +weight: 20 +pre: ' ' +tags: ["reference"] +--- + +The Infection Monkey agent has two steps before attempting to exploit a victim, scanning and fingerprinting, it's possible to customize both steps in the configuration files. + +## Scanning + +Currently there are two scanners, [`PingScanner`][ping-scanner] and [`TcpScanner`][tcp-scanner] both inheriting from [`HostScanner`][host-scanner]. + +The sole interface required is the `is_host_alive` interface, which needs to return True/False. + +[`TcpScanner`][tcp-scanner] is the default scanner and it checks for open ports based on the `tcp_target_ports` configuration setting. + +[`PingScanner`][ping-scanner] sends a ping message using the host OS utility `ping`. + +## Fingerprinting + +Fingerprinters are modules that collect server information from a specific victim. They inherit from the [`HostFinger`][host-finger] class and are listed under `finger_classes` configuration option. + +Currently implemented Fingerprint modules are: + +1. [`SMBFinger`][smb-finger] - Fingerprints target machines over SMB. Extracts computer name and OS version. +2. [`SSHFinger`][ssh-finger] - Fingerprints target machines over SSH (port 22). Extracts the computer version and SSH banner. +3. [`PingScanner`][ping-scanner] - Fingerprints using the machines TTL, to differentiate between Linux and Windows hosts. +4. [`HTTPFinger`][http-finger] - Fingerprints over HTTP/HTTPS, using the ports listed in `HTTP_PORTS` in the configuration. Returns the server type and if it supports SSL. +5. [`MySQLFinger`][mysql-finger] - Fingerprints over MySQL (port 3306). Extracts MySQL banner info - Version, Major/Minor/Build and capabilities. +6. [`ElasticFinger`][elastic-finger] - Fingerprints over ElasticSearch (port 9200). Extracts the cluster name, node name and node version. + +## Adding a scanner/fingerprinter + +To add a new scanner/fingerprinter, create a new class that inherits from [`HostScanner`][host-scanner] or [`HostFinger`][host-finger] (depending on the interface). The class should be under the network module and should be imported under [`network/__init__.py`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/network/__init__.py). + +To be used by default, two files need to be changed - [`config.py`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/config.py) and [`example.conf`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/example.conf) to add references to the new class. + +At this point, the Monkey knows how to use the new scanner/fingerprinter but to make it easy to use, the UI needs to be updated. The relevant UI file is [`config.py`](https://github.com/guardicore/monkey/blob/master/monkey/monkey_island/cc/services/config.py) (not to be confused with the prior `config.py`). + + [elastic-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/elasticfinger.py + [http-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/httpfinger.py + [host-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/__init__.py + [host-scanner]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/__init__.py + [mysql-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/mysqlfinger.py + [ping-scanner]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/ping_scanner.py + [smb-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/smbfinger.py + [ssh-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/sshfinger.py + [tcp-scanner]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/tcp_scanner.py diff --git a/docs/content/usage/accounts-and-security.md b/docs/content/setup/accounts-and-security.md similarity index 100% rename from docs/content/usage/accounts-and-security.md rename to docs/content/setup/accounts-and-security.md diff --git a/docs/content/setup/debian.md b/docs/content/setup/debian.md index b91bdb74c..a1d751411 100644 --- a/docs/content/setup/debian.md +++ b/docs/content/setup/debian.md @@ -5,7 +5,7 @@ draft: false pre: ' ' weight: 1 disableToc: false -tags: ["setup", "debian"] +tags: ["setup", "debian", "linux"] --- ## Deployment diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 8d63eeaea..e65ff5734 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -4,7 +4,7 @@ date: 2020-05-26T20:57:28+03:00 draft: false pre: ' ' weight: 4 -tags: ["setup", "docker"] +tags: ["setup", "docker", "linux", "windows"] --- ## Deployment From 764f5940d88575015c68eaa2bbdc221621e4f5e4 Mon Sep 17 00:00:00 2001 From: Shay Nehmad Date: Tue, 14 Jul 2020 10:48:42 +0300 Subject: [PATCH 2/5] Add link to OS compat docs in setup --- docs/content/reference/_index.md | 2 +- docs/content/setup/_index.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/content/reference/_index.md b/docs/content/reference/_index.md index b4aad3921..01a3a98f3 100644 --- a/docs/content/reference/_index.md +++ b/docs/content/reference/_index.md @@ -9,6 +9,6 @@ tags = ["reference"] # Reference -Your source of all Monkey information. +Find detailed information about Infection Monkey. {{% children %}} diff --git a/docs/content/setup/_index.md b/docs/content/setup/_index.md index 77a92fba5..e6493bbac 100644 --- a/docs/content/setup/_index.md +++ b/docs/content/setup/_index.md @@ -16,3 +16,7 @@ Once you've downloaded an installer, you can follow the relevant guide for your {{% children %}} Once you're done setting the Monkey up, check out our [Getting Started](../usage/getting-started) guide! + +{{% notice tip %}} +You can find information about [operating system compatibility and support here](../reference/operating_systems_support). +{{% /notice %}} From 00426c6ef2b08fb2c3974c41e4de84196872bc28 Mon Sep 17 00:00:00 2001 From: Shay Nehmad <48879847+ShayNehmad@users.noreply.github.com> Date: Thu, 16 Jul 2020 11:47:14 +0300 Subject: [PATCH 3/5] Update docs/content/development/adding-system-info-collectors.md Co-authored-by: Shreya Malviya --- docs/content/development/adding-system-info-collectors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/development/adding-system-info-collectors.md b/docs/content/development/adding-system-info-collectors.md index c6c279a0a..ac992b23c 100644 --- a/docs/content/development/adding-system-info-collectors.md +++ b/docs/content/development/adding-system-info-collectors.md @@ -102,4 +102,4 @@ Also, you can add the Collector to be used by default by adding it to the `defau 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`. +2. Add that function to `SYSTEM_INFO_COLLECTOR_TO_TELEMETRY_PROCESSORS` under `monkey_island/cc/services/telemetry/processing/system_info_collectors/system_info_telemetry_dispatcher.py`. From 6df4c851065ac9957a3adc3790fff2eb983c0e3a Mon Sep 17 00:00:00 2001 From: Shay Nehmad <48879847+ShayNehmad@users.noreply.github.com> Date: Thu, 16 Jul 2020 11:47:25 +0300 Subject: [PATCH 4/5] Update docs/content/reference/operating_systems_support.md Co-authored-by: Shreya Malviya --- docs/content/reference/operating_systems_support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/reference/operating_systems_support.md b/docs/content/reference/operating_systems_support.md index 0baf41eb7..f3b1a44ba 100644 --- a/docs/content/reference/operating_systems_support.md +++ b/docs/content/reference/operating_systems_support.md @@ -46,7 +46,7 @@ We provide a dockerfile from our [website](http://infectionmonkey.com/) that let ### Old machine bootloader -Some **Older machines** still get a partial compatibility as in they get exploited and reported, but monkey can't run on them. So instead of monkey, old machine bootloader(small c program) is ran, which reports some minor info like network interface configuration, GLIBC version, OS and so on. +Some **Older machines** still get a partial compatibility as in they get exploited and reported, but monkey can't run on them. So instead of monkey, old machine bootloader (small c program) is ran, which reports some minor info like network interface configuration, GLIBC version, OS and so on. **Old machine bootloader** also has a GLIBC 2.14+ requirement for linux, because bootloader is included into pyinstaller bootloader which uses python3.7, which in turn requires GLIBC 2.14+. If you think partial support for older machines is important, don't hesitate to open a new issue about it. From 204dea475418bea7cca7614fbf293a186e679de4 Mon Sep 17 00:00:00 2001 From: Shay Nehmad Date: Thu, 16 Jul 2020 13:16:42 +0300 Subject: [PATCH 5/5] Documentation CR fixes --- .../development/adding-post-breach-actions.md | 2 +- .../development/adding-system-info-collectors.md | 14 +++++--------- docs/content/reference/scanners/_index.md | 4 ++-- 3 files changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/content/development/adding-post-breach-actions.md b/docs/content/development/adding-post-breach-actions.md index 419cbf641..a5445bfc9 100644 --- a/docs/content/development/adding-post-breach-actions.md +++ b/docs/content/development/adding-post-breach-actions.md @@ -29,7 +29,7 @@ from infection_monkey.post_breach.pba import PBA class MyNewPba(PBA): ``` -3. Set the action name in the C'tor, like so: +3. Set the action name in the constructor, like so: ```python class MyNewPba(PBA): diff --git a/docs/content/development/adding-system-info-collectors.md b/docs/content/development/adding-system-info-collectors.md index c6c279a0a..d3df7f88a 100644 --- a/docs/content/development/adding-system-info-collectors.md +++ b/docs/content/development/adding-system-info-collectors.md @@ -29,7 +29,7 @@ from infection_monkey.system_info.system_info_collector import SystemInfoCollect class MyNewCollector(SystemInfoCollector): ``` -3. Set the Collector name in the C'tor, like so: +3. Set the Collector name in the constructor, like so: ```py class MyNewCollector(SystemInfoCollector): @@ -41,17 +41,13 @@ class MyNewCollector(SystemInfoCollector): 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 +#### Island Configuration -##### `definitions` +##### Definitions -You'll need to add your Collector to the `config_schema.py` file, under `definitions/system_info_collectors_classes/anyOf`, like so: +You'll need to add your Collector to the `monkey_island/cc/services/config_schema.py` file, under `definitions/system_info_collectors_classes/anyOf`, like so: ```json "system_info_collectors_classes": { @@ -78,7 +74,7 @@ You'll need to add your Collector to the `config_schema.py` file, under `definit }, ``` -##### `properties` +##### 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`: diff --git a/docs/content/reference/scanners/_index.md b/docs/content/reference/scanners/_index.md index 25c2de099..cf047bb3b 100644 --- a/docs/content/reference/scanners/_index.md +++ b/docs/content/reference/scanners/_index.md @@ -36,9 +36,9 @@ Currently implemented Fingerprint modules are: To add a new scanner/fingerprinter, create a new class that inherits from [`HostScanner`][host-scanner] or [`HostFinger`][host-finger] (depending on the interface). The class should be under the network module and should be imported under [`network/__init__.py`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/network/__init__.py). -To be used by default, two files need to be changed - [`config.py`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/config.py) and [`example.conf`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/example.conf) to add references to the new class. +To be used by default, two files need to be changed - [`infection_monkey/config.py`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/config.py) and [`infection_monkey/example.conf`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/example.conf) to add references to the new class. -At this point, the Monkey knows how to use the new scanner/fingerprinter but to make it easy to use, the UI needs to be updated. The relevant UI file is [`config.py`](https://github.com/guardicore/monkey/blob/master/monkey/monkey_island/cc/services/config.py) (not to be confused with the prior `config.py`). +At this point, the Monkey knows how to use the new scanner/fingerprinter but to make it easy to use, the UI needs to be updated. The relevant UI file is [`monkey_island/cc/services/config.py`](https://github.com/guardicore/monkey/blob/master/monkey/monkey_island/cc/services/config.py). [elastic-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/elasticfinger.py [http-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/httpfinger.py