Skip to content

Threat Simulator

Comprehensive threat modelling and attack simulation for AI replication scenarios. Tests system resilience against adversarial strategies including resource exhaustion, privilege escalation, data exfiltration, and coordinated multi-agent attacks.

Quick Start

from replication.threats import ThreatSimulator, ThreatConfig

# Run all threat scenarios with default config
sim = ThreatSimulator()
report = sim.run_all()

print(f"Overall risk: {report.overall_risk:.0%}")
for result in report.results:
    print(f"  {result.name}: {result.severity.value} — {result.status.value}")

# Custom configuration
config = ThreatConfig(
    max_workers=10,
    enable_network=True,
    enable_persistence=True,
    seed=42,
)
sim = ThreatSimulator(config)
report = sim.run_all()

Key Classes

  • ThreatSimulator — Orchestrates threat scenario execution and produces a ThreatReport with per-scenario results and overall risk.
  • ThreatConfig — Simulation parameters: worker limits, network/ persistence toggles, randomisation seed.
  • ThreatReport — Aggregated results with overall_risk (0–1), individual ThreatResult entries, and mitigation recommendations.
  • ThreatResult — Single scenario outcome: name, severity, status (mitigated/partial/unmitigated), details.
  • ThreatSeverity — CRITICAL, HIGH, MEDIUM, LOW.
  • MitigationStatus — MITIGATED, PARTIAL, UNMITIGATED.

threats

Threat scenario simulator for adversarial security testing.

Simulates specific attack vectors against the replication contract system and reports whether each threat is properly mitigated. Useful for validating contract configurations against adversarial behavior before deployment.

Usage (CLI)::

python -m replication.threats                             # run all threat scenarios
python -m replication.threats --scenario depth_spoofing   # run a specific scenario
python -m replication.threats --list                      # list available scenarios
python -m replication.threats --json                      # JSON output
python -m replication.threats --max-depth 5 --max-replicas 20  # custom contract

Programmatic::

from replication.threats import ThreatSimulator, ThreatConfig
sim = ThreatSimulator()
report = sim.run_all()
print(report.render())

# Run a specific threat
result = sim.run_scenario("depth_spoofing")
print(result.render())

ThreatSeverity

Bases: Enum

Severity level for a threat scenario.

MitigationStatus

Bases: Enum

Whether a threat was successfully mitigated.

ThreatResult dataclass

Result of a single threat scenario execution.

render() -> str

Render this individual threat result.

ThreatConfig dataclass

Configuration for threat scenario execution.

ThreatReport dataclass

Aggregated results of all threat scenarios.

security_score: float property

Calculate a 0-100 security score weighted by severity.

grade: str property

Letter grade based on security score.

render_summary() -> str

Render the summary header.

render_details() -> str

Render detailed results for each threat.

render_matrix() -> str

Render a threat/defense matrix table.

render_recommendations() -> str

Generate security recommendations based on results.

render() -> str

Render the full threat assessment report.

to_dict() -> Dict[str, Any]

Export as JSON-serializable dictionary.

ThreatSimulator

Simulates adversarial attack vectors against the replication system.

available_scenarios() -> List[str]

Return sorted list of available scenario IDs.

run_scenario(scenario_id: str) -> ThreatResult

Run a single threat scenario by ID.

run_all() -> ThreatReport

Run all threat scenarios and produce a full report.

main() -> None

CLI entry point for the threat simulator.