Application for detecting command and control (C2) communication through network traffic analysis.

---

🚧 project in development 🚧

---

Table of Contents

• 📝 Pre-requisites
  • 📦 Installing Required Packages and Tools
  • 🗝️ API Keys
• 🚨 Notice
• ⌨️ Usage
• 🪧 List of Features
  • ☑️ Implemented Features
    • General
    • Packet Capture Analysis
    • Detection
    • IoCs Enrichment
  • 📋 To-Do
    • General
    • Packet Capture Analysis
    • Detection
    • IoCs Enrichment
• 🧰 Development
  • 🏢 Virtual Environment

---

📝 Pre-requisites

• the current version requires Linux based operating system
• install Python version >= 3.8 < 3.11 (recommended 3.10)
• clone this project with the following command

$ git clone https://github.com/martinkubecka/C2Detective.git

📦 Installing Required Packages and Tools

$ pip install -r requirements.txt

Note: To learn more about different Scapy v2.x bundles visit https://scapy.readthedocs.io/en/latest/installation.html

• install wkhtmltopdf tool that provides a way to convert HTML web pages or documents to PDF format
• install Tshark which in our case is used for processing packets containg TLS certificate related information

Note: To find out more about wkhtmltopdf or Tshark, you can refer to the documentation or support resources provided by your package manager.

🗝️ API Keys

• enrichment engine uses the following APIs:

  • AbuseIPDB
  • AlienVault
  • Shodan
  • ThreatFox
  • URLhaus
  • VirusTotal

• if you want to use all the service listed above, add your API keys for AbuseIPDB, VirusTotal and Shodan to the config/config.yml file as shown in the config/example.yml

Note: You can enable or disable specific enrichment services by modifying the enrichment_services section in the configuration file config/config.yml.

---

🚨 Notice

• Scapy requires root privileges for sniffing
• running any python application with root privileges is not recommended for security concerns
• if you want to use provided sniffing option, you can assign CAP_NET_RAW and CAP_NET_ADMIN capabilities to the respective python binary
  • use the following commands before selecting the sniffing option
  • with the getcap command, we can verify assigned capabilities

$ which python3.10
/usr/bin/python3.10
$ sudo setcap 'CAP_NET_RAW+eip CAP_NET_ADMIN+eip' /usr/bin/python3.10
$ getcap /usr/bin/python3.10
/usr/bin/python3.10 cap_net_admin,cap_net_raw=eip

Note: Assigning capabilities to the python binary in the virtual environment is not possible because capabilities can be assigned only to the non-symlink files.

• do not forget to remove added capabilities, if they are no longer needed
• note that the following command will remove all assigned capabilities

$ sudo setcap -r /usr/bin/python3.10
$ getcap /usr/bin/python3.10
<no output>

---

⌨️ Usage

usage: c2detective [-h] [-q] (-i FILENAME | -p) [-c FILE] [-s] [-w] [-o PATH] [-d] [-g] [-e] [-utn] [-ucd] [-ujr]

Application for detecting command and control (C2) communication through network traffic analysis.

options:
  -h, --help                     show this help message and exit
  -q, --quiet                    do not print banner
  -c FILE, --config FILE         configuration file (default: 'config/config.yml')
  -s, --statistics               print packet capture statistics to the console
  -w, --write-extracted          write extracted data to a JSON file
  -o PATH, --output PATH         output directory file path for report files (default: 'reports/')

required options:
  -i FILENAME, --input FILENAME  input file (.cap / .pcap / .pcapng)
  -p, --packet-capture           start packet capture (setup in the configuration file)

enable options:
  -d, --dga                      enable DGA domain detection
  -g, --plugins                  enable plugins for extended detection capabilities
  -e, --enrich-iocs              enable data enrichment

update options:
  -utn, --update-tor-nodes       update tor node lists
  -ucd, --update-crypto-domains  update crypto / cryptojacking based sites list
  -ujr, --update-ja3-rules       update JA3 rules

---

🪧 List of Features

☑️ Implemented Features

General

• command-line interface (CLI) with argument parsing
• implemented logging
• load configurations from config file
  • enrichment services enabling and their API keys
  • option for setting custom thresholds for detection
• update options for Tor node list, crypto based sites list and Proofpoint ET JA3 rules
  • notify the user if Tor node list, crypto based sites list or Proofpoint ET JA3 rules is out-of-date
• option for packet capturing
• report C2 indicators detection score
• create HTML analysis report containing detailed information about detected C2 IoCs

Packet Capture Analysis

• load and parse provided packet capture with Scapy
  • extract various data from loaded packet capture
    • packet capture timestamps
    • public IP addresses
    • unique connections
    • TCP connections and their respective frequencies
    • packets with DNS layer
    • domain names from DNS queries
    • HTTP sessions
    • requested URLs
    • fields of interest from TLS certificates
• show custom packet capture statistics in terminal
• write extracted data from packet capture to a JSON file (extracted_data.json)

Detection

• detect domain names generated by Domain Generation Algorithms (DGA)
• detect Tor network traffic
• detect outgoing traffic to Tor exit nodes
• detect outgoing traffic to crypto / cryptojacking based sites
• detect connections with excessive frequency
• detect long connection
• detect unusual big HTTP response size
• detect known C2 values in TLS certificates
• detect signs of DNS based covert channels - DNS Tunneling
• detect known malicious JA3 (TLS negotiation) fingerprints
• integrate C2Hunter as a plugin for detection based on the processed threat feeds
  • detect C2 IPs which received or initiated connections
  • detect C2 domain names which received or initiated connections
  • detect requested C2 URLs
• write detected IoCs to a JSON file (detected_iocs.json)

IoCs Enrichment

• IoCs enrichment with AlienVault
• IoCs enrichment with AbuseIPDB
• IoCs enrichment with Shodan
• IoCs enrichment with ThreatFox
• IoCs enrichment with URLhaus
• IoCs enrichment with VirusTotal
• write enriched IoCs to a JSON file (enriched_iocs.json)

📋 To-Do

• following categories contains features that are in a queue for implementation
• this list is not exhaustive and additional features will be added during development

General

• no queued tasks at this moment

Packet Capture Analysis

• no queued tasks at this moment

Detection

• no queued tasks at this moment

IoCs Enrichment

• no queued tasks at this moment

---

🧰 Development

• contributions to this project are currently not allowed

🏢 Virtual Environment

1. use your package manager to install python-pip if it is not present on your system
2. install virtualenv
3. verify installation by checking the virtualenv version
4. inside the project directory (C2Detective) create a virtual environment called venv
5. activate it by using the source command
6. you can deactivate the virtual environment from the parent folder of venv directory with the deactivate command

$ sudo apt-get install python-pip
$ pip install virtualenv
$ virtualenv --version
$ cd C2Detective/
[C2Detective]$ virtualenv --python=python3.10 venv
[C2Detective]$ source venv/bin/activate
[C2Detective]$ deactivate

---

[ Table of Contents ]