Skip to content

README.md

Latest commit

 

History

History
184 lines (142 loc) · 6.3 KB

README.md

File metadata and controls

184 lines (142 loc) · 6.3 KB

PCAP Security Analyzer

Offline network forensics tool. Point it at a .pcap file and it detects C2 beaconing, data exfiltration, lateral movement, reconnaissance, and credential attacks. Outputs a report.json per file. No cloud lookups, no network calls.

Deploy

Local (Python)

pip install -r requirements.txt   # Python 3.11+ required

Docker

docker build -t pcap-analyzer .

# Mount your PCAPs and output folder at runtime — never bake them into the image
docker run --rm \
  -v /path/to/pcaps:/data \
  -v /path/to/output:/app/reports \
  pcap-analyzer analyze /data/capture.pcap --output /app/reports

Commands

analyze — single file

python analyze.py analyze <PCAP_FILE> [OPTIONS]
Flag Default Description
--output / -o ./reports Folder to write the report into
--confidence / -c 0.7 Minimum detector confidence to include a finding (0.0–1.0). Lower = more findings, more noise.
--severity-filter low Drop findings below this level: low medium high critical
--rules / -r (none) Path to a YAML rules file or folder. If omitted, the rule engine is skipped entirely — only the 5 behavioral detectors run.
--max-packets (all) Process only the first N packets. Useful for quick triage on large files.
--no-progress off Suppress the progress bar (cleaner output in scripts/CI).
--verbose / -v off Print full stack traces on errors.

Report is written to <output>/<pcap_stem>/report.json.

Examples:

# Detectors only (no rules)
docker run --rm -v /path/to/pcaps:/data -v /path/to/output:/app/reports \
  pcap-analyzer analyze /data/capture.pcap

# Detectors + bundled rules
docker run --rm -v /path/to/pcaps:/data -v /path/to/output:/app/reports \
  pcap-analyzer analyze /data/capture.pcap --rules /app/rules/malware_detection.yaml

# High-confidence, high-severity only
docker run --rm -v /path/to/pcaps:/data -v /path/to/output:/app/reports \
  pcap-analyzer analyze /data/capture.pcap --rules /app/rules/malware_detection.yaml \
  --confidence 0.9 --severity-filter high

# Quick triage — first 50k packets only
docker run --rm -v /path/to/pcaps:/data -v /path/to/output:/app/reports \
  pcap-analyzer analyze /data/capture.pcap --max-packets 50000

batch-analyze — whole directory

Processes every .pcap in a directory using parallel worker processes.

docker run --rm -v /path/to/pcaps:/data -v /path/to/output:/app/reports \
  pcap-analyzer batch-analyze <INPUT_DIR> [OPTIONS]
Flag Default Description
--output / -o ./reports Root output folder — each file gets its own subfolder
--workers / -w 8 Number of parallel worker processes
--batch / -b 8 Files dispatched per batch before waiting for results. Keeps memory bounded.
--confidence / -c 0.7 Minimum confidence threshold
--ext .pcap File extension to match (e.g. .pcapng)

Each file produces <output>/<pcap_stem>/report/report.json. Corrupt or unreadable files are logged and skipped — they do not stop the rest.

Examples:

# Analyze a full directory, 8 workers
docker run --rm -v /path/to/pcaps:/data -v /path/to/output:/app/reports \
  pcap-analyzer batch-analyze /data --output /app/reports --workers 8

# High-confidence findings only
docker run --rm -v /path/to/pcaps:/data -v /path/to/output:/app/reports \
  pcap-analyzer batch-analyze /data --output /app/reports --workers 8 --confidence 0.85

validate-rules — check rule files

Parses and validates YAML rule files without running any analysis.

docker run --rm pcap-analyzer validate-rules /app/rules/
docker run --rm pcap-analyzer validate-rules /app/rules/malware_detection.yaml

Prints rule counts by category and severity, and exits non-zero on any parse error.

Detectors vs Rules

The tool has two independent detection mechanisms that can be used together or separately:

Behavioral detectors (always run) — 5 Python modules that analyse flow-level patterns: timing, volumes, port behaviour, protocol anomalies. They catch things rules can't express, like beacon intervals or brute force rate.

Rule engine (opt-in via --rules) — evaluates your YAML rules against every packet and flow. The bundled rules/malware_detection.yaml contains 3,447 signature rules converted from Emerging Threats. Pass --rules to enable it; omit it to run detectors only.

Scenario Command
Detectors only (fast) pcap-analyzer analyze /data/capture.pcap
Rules only (signature match) pcap-analyzer analyze /data/capture.pcap --rules /app/rules/malware_detection.yaml --confidence 0.5
Both (full coverage) pcap-analyzer analyze /data/capture.pcap --rules /app/rules/malware_detection.yaml

Report format

report.json structure:

{
  "summary": {
    "total_findings": 12,
    "risk_score": 74,
    "severity_counts": { "critical": 2, "high": 5, "medium": 4, "low": 1 }
  },
  "findings": [
    {
      "type": "low_and_slow_c2",
      "severity": "high",
      "confidence": 0.85,
      "source_ip": "1.2.3.4",
      "destination": "5.6.7.8:443",
      "description": "...",
      "evidence": { "flows": 5, "avg_interval_seconds": 732 }
    }
  ]
}
  • type — which detector or rule triggered
  • severity — low / medium / high / critical
  • confidence — 0.0–1.0; filter with --confidence
  • evidence — raw numbers behind the alert

Project Structure

├── analyze.py                  # CLI entry point
├── Dockerfile
├── requirements.txt
├── rules/
│   └── malware_detection.yaml  # 3,447 merged ET rules
└── pcap_analyzer/
    ├── cli.py
    ├── core/
    │   ├── packet_parser.py    # Parses .pcap, rebuilds flows
    │   └── analyzer.py         # Orchestrates detectors + rules + reporter
    ├── detectors/
    │   ├── c2_detector.py
    │   ├── exfiltration.py
    │   ├── lateral_movement.py
    │   ├── credential_access.py
    │   └── reconnaissance.py
    ├── rules/
    │   └── rule_engine.py      # YAML rule parser and evaluator
    └── reporters/
        └── json_reporter.py