{"id":20010206,"url":"https://github.com/activecm/threat-tools","last_synced_at":"2025-05-12T17:23:42.249Z","repository":{"id":37623856,"uuid":"355597130","full_name":"activecm/threat-tools","owner":"activecm","description":"Tools for simulating threats","archived":false,"fork":false,"pushed_at":"2023-10-27T22:10:10.000Z","size":55,"stargazers_count":183,"open_issues_count":0,"forks_count":32,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-12T17:23:41.095Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/activecm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-07T15:35:40.000Z","updated_at":"2025-03-17T00:55:41.000Z","dependencies_parsed_at":"2022-09-06T09:12:33.330Z","dependency_job_id":"de57de54-428d-40b4-99b2-77eb3007d6e0","html_url":"https://github.com/activecm/threat-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fthreat-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fthreat-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fthreat-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecm%2Fthreat-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/activecm","download_url":"https://codeload.github.com/activecm/threat-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253785187,"owners_count":21963926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T07:18:51.450Z","updated_at":"2025-05-12T17:23:42.222Z","avatar_url":"https://github.com/activecm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003ethreat-tools\u003c/h1\u003e\n\nThis repository contains several scripts that will allow you to mimic a compromised system calling home to a command and control (C2) server. None of the tools exfiltrate any data and are designed to test your environment's ability to detect a wide range of C2 channels.\n\n## Table of Contents\n[Overview](#overview)\u003c/br\u003e\n[Example Setup](#example-setup)\u003c/br\u003e\n[`simple-listener.sh`](#simple-listenersh)\u003c/br\u003e\n[`beacon-simulator.py`](#beacon-simulatorpy)\u003c/br\u003e\n[`beacon-simulator.sh`](#beacon-simulatorsh)\u003c/br\u003e\n[`simple-beacon.sh`](#simple-beaconsh)\u003c/br\u003e\n[Python Script Pairs](#python-script-pairs)\u003c/br\u003e\n[Running Tools in the Background with `screen`](#running-tools-in-the-background-with-screen)\n\nSome names were changed from previous versions in order to be more intuitive. Navigate to the following section to reference name changes if you do not see your script in the Table of Contents:\u003c/br\u003e\n\n[Script Name Changes](#script-name-changes)\n\n\n## Overview\nIn order to run these scripts, you will need two systems: one to act as the compromised client sending the beacon, and one to act as the C2 server. The client will need to run one of the beacon simulator scripts, and the server will need to run one of the scripts to set up a listener. With exception to the scripts within `python-scripts`, all beacon simulators are meant to be used in tandem with `simple-listener.sh` running on the server. \n\nThe only exception to this is if the client is running `simple-beacon.sh`, which can simulate beacon traffic by repeatedly sending web requests to any public web server.\n\nFor the majority of users, `beacon-simulator.py` and `simple-listener.sh` will be sufficient to simulate a C2 channel. Alternative beacon simulators are available in the `shell-scripts` and `python-scripts` directories.\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## Example Setup\nThis guide will walk you through setting up a C2 channel with `simple-listener.sh` running on the device acting as the server and `beacon-simulator.py` running on the device acting as the compromised client system.\n\n### Setting up the Server\n1. Clone this repository onto the server.\n1. Install `ncat` if it is not already installed. (While `simple-listener.sh` can run with `netcat` and `nc`, it may have issues with UDP timeouts.)\n1. Navigate into the `threat-tools` directory.\n1. Run the following command to set up port 9000 to listen for TCP connections:\n```\n./simple-listener.sh 9000\n```\nIf successful, the console will print `Starting listener on TCP port 9000`.\n\n### Setting up the Client\n1. Clone this repository onto the client.\n1. Install `python3` if it is not already installed. Most systems have it.\n1. Navigate into the `threat-tools` directory.\n1. Run the following command, replacing `\u003cSERVER IP\u003e` with the server's IP address, to establish a TCP beacon with a 30-second interval with 5 seconds of jitter and a maximum payload of 1024 bytes.\n```\npython3 ./beacon-simulator.py -ip \u003cSERVER IP\u003e -p 9000 -i 30 -j 5 -m 1024\n```\nIf successful, the console will start printing a message specifying the amount of jitter, the data sent (a random string of `a`'s), and the total number of beacons sent.\n\nTo close the beacon, use \"Ctrl + C\" in each terminal to stop the scripts.\n\n### Next Steps\nTo view more detailed information about each script used in this example and how to customize them, you can read their sections of the README:\n- [`simple-listener.sh`](#simple-listenersh)\n- [`beacon-simulator.py`](#beacon-simulatorpy)\n\nThe README also contains detailed information for all other scripts included in this repository.\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## `simple-listener.sh`\n`simple-listener.sh` should run on the machine simulating the C2 server. It will set up a listening port for either TCP or UDP connections.\n\nIt should be used in conjunction with `beacon-simulator.py`, `beacon-simulator.sh`, or `simple-beacon.sh` running on the machine simulating the compromised client.\n\n### Dependencies:\nEnsure you have the network utility `ncat` installed on the system running the script.\n\n**NOTE:** While the script can work with `netcat` and `nc`, both have shown issues with handling UDP timeouts. We highly encourage you to install `ncat`.\n\n### Command Syntax:\n```\n./simple-listener.sh \u003cport\u003e \u003cprotocol\u003e\n```\n`port`: The port number you want to set up as the listener. Must be root user to listen on ports \u003c= 1024.\u003c/br\u003e\n`protocol` (optional): The protocol to listen for. Accepts either `udp` or `tcp`. Defaults to `tcp`.\n\n### Example Commands:\n```\n./simple-listener.sh 9000 udp\n```\nSets up port 9000 to listen for UDP connections.\n\n```\n./simple-listener.sh 3333\n```\nSets up port 3333 to listen for TCP connections.\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## `beacon-simulator.py`\n`beacon-simulator.py` should run on the machine simulating the compromised client. It will allow you to send a jittered beacon with a payload of random size to the targeted IP. The IP should point to the machine acting as the C2 server running `./simple-listener.sh`.\n\n### Dependencies\nYou will need to use the `python3` interpreter to run the script. Most OS's come with this already installed. You will need to install it if the system running the script does not have it.\n\n### Command Syntax\n```\npython3 ./beacon-simulator.py \u003cip\u003e \u003cport\u003e \u003cinterval\u003e \u003cjitter\u003e \u003cmax payload\u003e \u003cprotocol\u003e\n```\n`ip`: The IP address of the server.\u003c/br\u003e\n`port`: The server port listening for the connection.\u003c/br\u003e\n`interval`: The amount of time in seconds between beacons.\u003c/br\u003e\n`jitter`: The amount of jitter in seconds.\u003c/br\u003e\n`max payload`: The beacon's maximum payload size in bytes. The payload is a random string of a's ranging from 0 to the maximum payload size.\u003c/br\u003e\n`protocol` (optional): The protocol of the beacon. Accepts either `--tcp` or `--udp`. The TCP protocol is used by default.\u003c/br\u003e\n\n### Example Commands\n```\npython3 ./beacon-simulator.py -ip 192.168.56.104 -p 9000 -i 30 -j 5 -m 1024\n```\nSends a random payload of up to 1024 bytes to port 9000 on the device at IP 192.168.56.104 every 25-35 seconds using the TCP protocol.\n```\npython3 ./beacon-simulator.py -ip 192.168.56.101 --port 3333 --interval 300 --jitter 8 --max_payload 256 --udp\n```\nSends a random payload of up to 256 bytes to port 3333 on the device at IP 192.168.56.101 every 292-308 seconds using the UDP protocol.\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## `beacon-simulator.sh`\n`beacon-simulator.sh` should run on the machine simulating the compromised client. It will allow you to send a jittered beacon with a payload of random size to the targeted IP. The IP should point to the machine acting as the C2 server running `./simple-listener.sh`.\n\n### Dependencies\n\nPlease ensure you have the following tools installed on the system running the script:\n\n- `ncat`: To make TCP or UDP connections.\n- `hping3`: To send ICMP packets.\n\n**NOTE:** While the script can work with `netcat` and `nc`, both have shown issues with handling UDP timeouts. We highly encourage you to install `ncat`.\n\n### Command Syntax\n```\n./beacon-simulator.sh \u003cip\u003e \u003cport\u003e \u003cinterval\u003e \u003cjitter\u003e \u003cprotocol\u003e \u003cmax payload\u003e\n```\n`ip`: The IP address of the server.\u003c/br\u003e\n`port`: The server port listening for the connection. (Or the ICMP type: 8 = `ping`, 13 = `timestampreq`, 17 = `addrmaskreq`)\u003c/br\u003e\n`interval`: The amount of time in seconds between beacons.\u003c/br\u003e\n`jitter`: The amount of jitter in seconds.\u003c/br\u003e\n`protocol` (optional): The protocol of the beacon. Accepts `tcp`, `udp`, or `icmp`. Defaults to `tcp`.\u003c/br\u003e\n`max payload` (optional): The beacon's maximum payload size in bytes. The payload is a random string of a's ranging from 0 to the maximum payload size. Defaults to `1424`.\u003c/br\u003e\n\n### Example Commands\n```\n./beacon-simulator.sh 192.168.56.104 9000 30 5\n```\nSends a random payload of up to 1424 bytes to port 9000 on the device at IP 192.168.56.104 every 25-35 seconds using the TCP protocol.\n\n```\n./beacon-simulator.sh 192.168.56.101 3333 300 8 udp 256\n```\nSends a random payload of up to 256 bytes to port 3333 on the device at IP 192.168.56.101 every 292-308 seconds using the UDP protocol.\n\n```\n./beacon-simulator.sh 192.168.56.102 8 10 2 icmp\n```\nPings the server at 192.168.56.102 every 8-12 seconds.\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## `simple-beacon.sh`\n`simple-beacon.sh` should run on the machine simulating the compromised client. It sends a very simple HTTP request with a custom user-agent string (`Modzilla/0.0001(Atari7800)`) to a specified IP address or FQDN every 200-350 seconds. This script can be used on its own without any additional scripts such as `simple-listener.sh`.\n\n### Dependencies\nThis script uses common utilities commonly pre-installed on Unix-like systems. You should not need to install them. For your reference, the required utilities are:\n\n- `curl`\n- `shuf`\n- `sleep`\n\n#### Command Syntax\n```\n./simple-beacon.sh \u003cIP or FQDN\u003e\n```\n`IP or FQDN`: The IP address or FQDN of the server.\n\n#### Example Commands\n```\n./simple-beacon.sh activecountermeasures.com\n```\nSimulates a jittered beacon by sending HTTP requests to activecountermeasures.com\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## Python Script Pairs\nThe scripts within the `python-scripts` directory work in pairs. `tcp-client.py` works with `tcp-server.py`, and `udp-client.py` works with `udp-server.py`. Unlike the other threat tools, these scripts can send a beacon to more than one server. Both client scripts will require editing the code so the IP addresses match your server IP(s). You can also edit the code to configure the server port for the C2 channel, the payload size, and the beaconing interval if you disagree with the defaults.\n\nDefault Server Port: 9000\u003c/br\u003e\nDefault Payload Size: 0 - 1200 bytes\u003c/br\u003e\nDefault Beaconing Interval: 30 - 60 seconds\n\n### Dependencies\nThese scripts require the following tools to be installed on both systems.\n\n- `python3`: Interpreter to run the script. Most systems have this pre-installed.\n- `pycryptodome`: Python cryptographic library.\n- `pip3`: Needed to install `pycryptodome` if it is not already installed.\n\n#### Installing `pycryptodome`\nIf your system does not have `pycryptodome` installed, follow these instructions:\n\n1. Install the Python package manager, `pip3`.\n1. Run the following command:\n```\npip3 install pycryptodome\n```\n\n### Configurations\n\n#### Configuring the Client Files\n1. On the client device, open `tcp-client.py` or `udp-client.py` in a text editor such as nano.\n1. Navigate to the line starting with `server =` followed by a list of IP addresses and replace them with the IP Address(es) of your server(s).\n1. (optional) Change the server port at the line with `SERVER_PORT = 9000`. (If you change the port number, you *must* edit the corresponding `-server.py` file to match.)\n1. (optional) Change the payload size range at the line with `m = randint(0, 1200)`.\n1. (optional) Change the beaconing interval at the line with `rsleep = random.randint(30, 60)`.\n1. Save the changes and exit.\n\n#### Configuring Server Files (optional)\nNOTE: This is only necessary if you changed the server port number in a `-client.py` script. For example, if you changed the server port in `tcp-client.py`, you *must* edit `tcp-server.py` script to match.\n1. On the server device, open the corresponding `-server.py` file in a text editor such as nano.\n1. Change the server port number at the line with `SERVER_PORT = 9000` to match the number you chose in the corresponding `-client.py` file.\n1. Save the changes and exit.\n\n### Running the Script Pairs\n\n#### TCP Beacon Pair\nOn the server machine, navigate into the `python-scripts` directory and run:\n\n```\npython3 ./tcp-server.py\n```\n\nOn the client machine, navigate into the `python-scripts` directory and run:\n\n```\npython3 ./tcp-client.py\n```\n\n#### UDP Beacon Pair\nOn the server machine, navigate into the `python-scripts` directory and run:\n\n```\npython3 ./udp-server.py\n```\n\nOn the client machine, navigate into the `python-scripts` directory and run:\n\n```\npython3 ./udp-client.py\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## Running Tools in the Background with `screen`\nYou can use the `screen` utility to run these scripts in a separate session in the background and access it later. To do so, simply add `screen -S \u003cname\u003e -d -m` at the beginning of the command, replacing `\u003cname\u003e` with a name for the session.\n\n### Dependencies\nYou may need to install `screen` if it is not already installed on your system.\n\n### Start Session in the Background\n```\nscreen -S my-session -d -m ./simple-beacon.sh 192.168.56.104\n```\nThis will run `simple-beacon.sh` in the background.\n\nIf you wish to access the session later and turn it off, you can do so by using `screen -r \u003cname\u003e` to re-attach the session to the terminal window then pressing \"Ctrl + C\".\n\n### Re-attaching the Session\n```\nscreen -r my-session\n```\nThis will re-attach `my-session` to the terminal window. You can then stop `simple-beacon.sh` by pressing \"Ctrl + C\".\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## File Name Changes\nFile names have changed from previous versions in order to be more intuitive and consistent. Returning users can reference the table below to confirm name changes.\n\n| Old Name            | New Name            |\n| ------------------- | ------------------- |\n| beacon_simulator.py | beacon-simulator.py |\n| beacon-test         | simple-beacon.sh    |\n| tcp_client.py       | tcp-client.py       |\n| tcp_server.py       | tcp-server.py       |\n| udp_client.py       | udp-client.py       |\n| udp_server.py       | udp-server.py       |\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#table-of-contents\"\u003eBack to Top\u003c/a\u003e\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factivecm%2Fthreat-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Factivecm%2Fthreat-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factivecm%2Fthreat-tools/lists"}