ThreatLens

# 1. Clone & install
git clone https://github.com/AbdaullahAG/threatlens.git
cd threatlens
pip install -r requirements.txt

# 2. Configure your API keys
cp config/keys.env.example config/keys.env
# → edit config/keys.env and fill in your keys

# 3. Run your first scan
python main.py -i 45.33.32.156

pip install --require-hashes -r requirements.lock

threat_intel_tool/
├── main.py                      # CLI entry point & argument parser
├── requirements.txt             # Runtime dependencies
├── requirements-dev.txt         # Dev/CI tooling (ruff, bandit, pip-audit, pip-tools)
├── requirements.lock            # Pinned lockfile with SHA-256 hashes
├── pytest.ini                   # pytest configuration (marks, etc.)
├── config/
│   └── keys.env                 # API keys (copy from keys.env.example)
├── output/                      # Generated reports land here
├── src/
│   ├── engine.py                # Main orchestrator (collect → enrich → report)
│   ├── models.py                # IOC & EnrichmentResult dataclasses
│   ├── storage.py               # SQLite cache & investigation history
│   ├── parsers/
│   │   └── ioc_parser.py        # Regex-based IOC extractor with validation
│   ├── enrichers/
│   │   ├── base.py              # Abstract base — safe HTTP client (redirect-block, budget, retry)
│   │   ├── registry.py          # Enricher dispatcher
│   │   ├── abuseipdb.py         # AbuseIPDB      (IP)
│   │   ├── virustotal.py        # VirusTotal     (IP / Domain / URL / Hash)
│   │   ├── otx.py               # AlienVault OTX (IP / Domain / URL / Hash)
│   │   ├── shodan.py            # Shodan         (IP)
│   │   ├── urlscan.py           # URLScan.io     (URL / Domain)
│   │   └── nvd.py               # NVD / NIST     (CVE — no key required)
│   ├── reporters/
│   │   ├── excel_reporter.py    # Color-coded Excel reports
│   │   ├── other_reporters.py   # JSON & CSV output
│   │   └── terminal_display.py  # Rich terminal tables
│   └── utils/
│       ├── config.py            # API key loader & runtime config
│       ├── logger.py            # Rich logging setup
│       ├── banner.py            # ASCII banner
│       ├── quota.py             # Per-run request budget (thread-safe)
│       └── security.py         # IOC validation, formula neutralisation, secret redaction
└── tests/
    ├── conftest.py              # pytest fixtures & --run-e2e flag
    ├── test_core.py             # IOC parser, verdict logic, cache round-trip (34 tests)
    ├── test_enrichers.py        # BaseEnricher HTTP edge-cases — mock only (9 tests)
    ├── test_reporters.py        # Excel/CSV formula protection + SQLite integration (17 tests)
    └── test_cli_e2e.py          # Full CLI run against real NVD API (opt-in, --run-e2e)

# Run all unit and integration tests (no network required)
pytest tests/ -v --ignore=tests/test_cli_e2e.py

# With coverage report
pytest tests/ -v --ignore=tests/test_cli_e2e.py --cov=src --cov-report=term-missing

# Run the end-to-end CLI test (makes a real NVD request)
pytest tests/test_cli_e2e.py --run-e2e -v

╭──────────────────────────── IOC Collection ─────────────────────────────╮
│ Found 4 IOCs to investigate                                              │
│   CVE: 1  Domain: 1  Hash: 1  IP: 1                                     │
╰──────────────────────────────────────────────────────────────────────────╯
✓ Active APIs: abuseipdb, virustotal, otx, shodan, urlscan, nvd

🌐 IP Address Results
┌─────────────────┬──────────────┬──────────┬─────────┬────────────────────┐
│ IP Address      │ Verdict      │ Abuse %  │ Country │ ISP / Org          │
├─────────────────┼──────────────┼──────────┼─────────┼────────────────────┤
│ 45.33.32.156    │ Suspicious   │ 42       │ US      │ Linode             │
└─────────────────┴──────────────┴──────────┴─────────┴────────────────────┘

⚠️  CVE Results
┌──────────────────┬──────────┬──────┬──────────────┐
│ CVE ID           │ Severity │ CVSS │ Published    │
├──────────────────┼──────────┼──────┼──────────────┤
│ CVE-2021-44228   │ Critical │ 10.0 │ 2021-12-10   │
└──────────────────┴──────────┴──────┴──────────────┘