Reverse Shell Detection Lab

Reverse Shell Detection Lab is a defensive blue-team project for detecting reverse shell patterns from safe, synthetic logs. It is intentionally focused on detection engineering, rule validation, and explainable reporting.

Safety Scope

• Defensive detection lab only.
• Fixtures are synthetic logs, not executable payloads.
• No AV/EDR bypass, persistence, exploitation, or payload generation.
• Examples use documentation IP ranges and redacted command context.

MVP Architecture

local scenario fixtures
        |
        v
process + network logs
        |
        v
Sigma-like YAML rules
        |
        v
process/network correlation engine
        |
        v
JSON or Markdown findings report

Future layers can ingest Zeek conn.log, Suricata eve.json, and generated PCAP fixtures behind the same event model.

Quick Start

py -m venv .venv
.\.venv\Scripts\python -m pip install -e .[dev]
.\.venv\Scripts\revshell-lab validate-rules
.\.venv\Scripts\revshell-lab scan --format markdown --output reports/sample.md
.\.venv\Scripts\python -m pytest

Without installing the console script:

py -m pip install -e .[dev]
py -m revshell_lab scan --format json

Project Layout

• src/revshell_lab/ - CLI, event loaders, rule parser, detector, report rendering.
• rules/reverse_shell_patterns.yml - initial Sigma-inspired detection rules.
• data/fixtures/ - benign and suspicious synthetic log fixtures.
• tests/ - rule validation and false-positive checks.
• docs/IMPLEMENTATION_PLAN.md - Notion-derived implementation plan.

Current Detection Logic

The first detector correlates suspicious process command-line patterns with outbound network activity from the same host and process within a configurable time window.

Initial detections cover:

• Interactive shell process with outbound connection.
• Netcat-like exec pattern with outbound connection.
• PowerShell hidden/no-profile shell-like behavior with outbound connection.

Supported Inputs

• Native lab JSONL process and network events.
• Zeek conn.log exported as JSON lines.
• Suricata eve.json flow events.

Use --network-format auto, jsonl, zeek, or suricata.

revshell-lab scan --network-log data\fixtures\zeek_conn.jsonl --network-format zeek
revshell-lab scan --network-log data\fixtures\suricata_eve.jsonl --network-format suricata

Ethics Note

This repository demonstrates mature security practice: it helps defenders recognize suspicious process/network behavior while avoiding weaponized code. Contributions should preserve that boundary.