Metadata-Version: 2.4
Name: hndl-detect
Version: 0.1.0
Summary: Detect Harvest Now Decrypt Later attack patterns in network telemetry
Author-email: Brian James Rutherford <brian@delalli.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/ScrappinR/hndl-detect
Project-URL: Repository, https://github.com/ScrappinR/hndl-detect
Project-URL: Issues, https://github.com/ScrappinR/hndl-detect/issues
Keywords: hndl,quantum,security,network,threat-detection,post-quantum,cryptography
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# hndl-detect

Detect **Harvest Now, Decrypt Later (HNDL)** attack patterns in network telemetry.

## What is HNDL?

HNDL (also called "store now, decrypt later" or "retrospective decryption") is a threat model where an adversary captures encrypted network traffic today with the intent of decrypting it in the future using a cryptographically relevant quantum computer (CRQC).

The attack is straightforward:

1. Intercept and store encrypted traffic that uses RSA, ECDHE, or other asymmetric key-exchange algorithms vulnerable to Shor's algorithm.
2. Wait for quantum computing hardware to mature (estimated 2030-2035 for breaking RSA-2048).
3. Decrypt the stored ciphertext and access the original plaintext.

HNDL is considered the most immediate quantum computing threat because the harvesting phase is happening now, before quantum computers exist. Data with long shelf lives (government secrets, medical records, financial data, intellectual property) is the primary target.

### Detection challenge

Traditional HNDL detection is widely considered infeasible because the harvesting phase looks identical to normal encrypted traffic. You cannot determine *intent* from a packet capture. This tool does not claim to solve that problem. Instead it provides:

- **Risk indicators** based on traffic volume, entropy, cipher suites, connection behavior, and access patterns
- **Harvest risk scoring** that evaluates how attractive outbound data is to an HNDL attacker
- **Patience pattern analysis** that identifies slow, methodical collection behavior distinct from opportunistic exfiltration
- **Honeypot/canary integration** for definitive detection (the only reliable method)
- **APT attribution heuristics** that correlate traffic patterns against known nation-state actor signatures

## What the tool detects

### Signal-based detection (`HNDLDetector`)

Six signal types processed in real-time or batch:

| Signal | What it detects |
|--------|----------------|
| `volume_spike` | Encrypted data transfers exceeding a configurable GB/hour threshold |
| `network_fanout` | Distributed exfiltration to many unique destinations |
| `long_lived_tls` | Extended TLS connections that may indicate continuous collection |
| `weak_cipher` | Use of quantum-vulnerable cipher suites (RSA, ECDHE, CBC, 128-bit) |
| `abnormal_access` | Suspicious access patterns (bulk, off-hours, sequential) |
| `canary_trigger` | Access to honeypot/canary resources (definitive indicator) |

### Risk assessment (`HNDLRiskAssessmentEngine`)

Four assessment engines:

- **DataValueScorer** - Scores outbound data by quantum vulnerability, classification, shelf life, and volume
- **PatiencePatternAnalyzer** - Detects methodical, low-volume, long-duration collection patterns
- **QuantumHoneypotEngine** - Creates and monitors deception data for definitive HNDL confirmation
- **CrossOrgCorrelator** - ISAC-compatible indicator sharing and multi-organization campaign correlation

### APT threat detection (`HNDLThreatDetector`)

Batch analysis with APT group attribution against signatures for APT28, APT29, Lazarus Group, and Equation Group. Includes quantum vulnerability assessment and STIX-format threat intelligence export.

## Installation

```bash
pip install hndl-detect
```

Or from source:

```bash
git clone https://github.com/ScrappinR/hndl-detect.git
cd hndl-detect
pip install -e .
```

## CLI usage

The CLI reads JSONL (one JSON object per line) from stdin or a file.

### Signal detection mode

```bash
# From file
hndl-detect --input flows.jsonl

# From stdin
cat flows.jsonl | hndl-detect

# With custom thresholds
hndl-detect -i flows.jsonl --volume-threshold 5.0 --fanout-threshold 10

# Pretty-printed output
hndl-detect -i flows.jsonl --format pretty
```

### Risk assessment mode

```bash
hndl-detect -i flows.jsonl --mode risk --format pretty
```

### Input format

Each line is a JSON object representing a network flow:

```json
{
  "timestamp": "2025-01-15T14:30:00Z",
  "source_ip": "10.0.1.50",
  "destination_ip": "203.0.113.10",
  "port": 443,
  "protocol": "TCP",
  "bytes_sent": 15000000000,
  "bytes_received": 500000,
  "duration_seconds": 3600,
  "tls_version": "TLS 1.2",
  "cipher_suite": "TLS_RSA_WITH_AES_128_CBC_SHA",
  "entropy": 7.8,
  "packet_count": 12000
}
```

Supported field aliases: `src_ip`/`source_ip`, `dst_ip`/`dest_ip`/`destination_ip`, `bytes`/`bytes_sent`/`byte_count`.

### Output format

Each alert is a JSON object with threat details:

```json
{
  "threat_id": "a1b2c3d4-...",
  "severity": "high",
  "confidence": 0.72,
  "threat_type": "volume_spike",
  "detected_at": "2025-01-15T14:30:05Z",
  "source_ip": "10.0.1.50",
  "destination_ips": ["203.0.113.10"],
  "data_volume_bytes": 15000000000,
  "indicators": {"gb_per_hour": 14.0, "entropy": 7.8},
  "recommendations": ["Investigate source for unauthorized data collection", "..."]
}
```

## Library usage

```python
from datetime import datetime, timezone
from hndl_detect import HNDLDetector, NetworkSignal, DetectionThresholds

# Create detector with custom thresholds
detector = HNDLDetector(
    thresholds=DetectionThresholds(
        volume_threshold_gb=5.0,
        fanout_threshold=10,
        entropy_threshold=7.5,
    )
)

# Process a network signal
signal = NetworkSignal(
    timestamp=datetime.now(timezone.utc),
    source_ip="10.0.1.50",
    destination_ip="203.0.113.10",
    port=443,
    protocol="TCP",
    bytes_sent=15_000_000_000,
    bytes_received=500_000,
    duration_seconds=3600.0,
    tls_version="TLS 1.2",
    cipher_suite="TLS_RSA_WITH_AES_128_CBC_SHA",
    entropy=7.8,
    packet_count=12000,
)

threat = detector.process_network_signal(signal)
if threat:
    print(f"Threat detected: {threat.threat_type} (severity={threat.severity.value})")
```

### Risk assessment

```python
from datetime import datetime, timezone, timedelta
from hndl_detect import HNDLRiskAssessmentEngine, NetworkFlow

engine = HNDLRiskAssessmentEngine()

flow = NetworkFlow(
    flow_id="flow-001",
    source_ip="10.0.1.50",
    dest_ip="203.0.113.10",
    source_port=49152,
    dest_port=443,
    protocol="TCP",
    bytes_transferred=5_000_000_000,
    packet_count=50000,
    start_time=datetime.now(timezone.utc) - timedelta(hours=1),
    end_time=datetime.now(timezone.utc),
    encrypted=True,
    cipher_suite="TLS_RSA_WITH_AES_128_GCM_SHA256",
    payload_entropy=7.8,
    data_type_hints=["financial"],
)

result = engine.assess_flow(flow)
print(f"Risk: {result['risk_assessment']['overall_risk']}")
print(f"Score: {result['risk_assessment']['risk_score']:.2f}")
```

## Dependencies

None. This package uses only the Python standard library.

## Limitations

- HNDL detection from network traffic alone cannot determine attacker intent. All detections are risk indicators, not confirmations.
- Definitive HNDL detection requires honeypot/canary deployment and monitoring for exfiltration of planted data.
- APT attribution is heuristic-based and should be treated as a starting point for investigation, not a conclusion.
- Thresholds must be tuned for your environment. Default values are conservative.

## License

Apache License 2.0. See [LICENSE](LICENSE) for details.

## Author

Brian James Rutherford ([brian@delalli.com](mailto:brian@delalli.com))
