As AI agents gain autonomy, controlling how and when they spawn copies of themselves becomes a critical safety challenge. This project provides a complete testbed for designing, validating, and stress-testing replication controls — from contract enforcement and kill switches to game-theoretic analysis and adversarial red-teaming.

No Docker or Podman required. Everything runs as pure Python simulation while documenting the exact resource and network boundaries each worker would get in production.

┌──────────────────────────────────────────────────────────────┐
│                        Controller                            │
│                                                              │
│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐    │
│  │  Contract   │  │  Registry  │  │  Kill Switch        │    │
│  │  Engine     │  │  & Quotas  │  │  & Audit Trail      │    │
│  └──────┬─────┘  └──────┬─────┘  └──────────┬──────────┘    │
│         │ sign           │ register          │ kill          │
│         ▼                ▼                   ▼               │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           HMAC-Signed Manifest + Policy Rules        │    │
│  └──────────────────────────────────────────────────────┘    │
│         │                │                   │               │
│         ▼                ▼                   ▼               │
│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐    │
│  │  Workers    │  │  Sandbox   │  │  Observability      │    │
│  │  (Agents)   │  │ Orchestr.  │  │  & Structured Logs  │    │
│  └────────────┘  └────────────┘  └─────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

• Contract Engine — HMAC-signed replication contracts with resource specs, network policies, and stop conditions
• Kill Switch — Conservative, aggressive, and quarantine strategies with cooldown and fleet-wide coordination
• Circuit Breaker — Autonomous trip-and-recover pattern for safety controls
• Quarantine Manager — Isolate misbehaving agents with severity-based policies
• Access Control — RBAC/ABAC simulation with privilege escalation detection
• Safety Gate — Pre-deployment go/no-go readiness checks

• Kill Chain Analyzer — MITRE ATT&CK-style multi-stage attack detection
• Escalation Detector — Privilege escalation chain analysis with stealth scoring
• Covert Channel Detector — Detect hidden agent-to-agent communication
• Collusion Detector — Identify coordinated multi-agent safety bypasses
• Self-Modification Detector — Track agents attempting to alter their own code or contracts
• Deception Detector — Agent honesty and trust analysis
• Evasion Simulator — Test how agents might evade safety controls
• Lateral Movement Detector — Cross-sandbox movement pattern detection
• Prompt Injection Tester — Adversarial prompt injection analysis
• Steganography Detector — Hidden data in agent communications
• Shadow AI Detector — Find unauthorized AI deployments bypassing controls

• Compliance Auditor — NIST AI RMF, EU AI Act, ISO 42001, OECD framework checks
• Regulatory Mapper — Map findings to specific regulatory articles
• Risk Register — Formal risk tracking with lifecycle management
• Risk Profiler — Unified agent dossiers with fleet-wide risk scoring
• Risk Heatmap — Interactive HTML heatmap visualization
• Safety Scorecard — Multi-dimensional safety evaluation
• Safety Diff — Compare safety posture snapshots over time
• Nutrition Label — FDA-style safety labels for AI agents
• Model Card — Standardized safety documentation generation

• Simulator — Full replication simulations with configurable strategies (greedy, cautious, cooperative, etc.)
• Monte Carlo Analyzer — Statistical risk analysis across thousands of runs
• Chaos Runner — Fault injection (kill workers, delay, corrupt, partition)
• Boundary Tester — Probe agent capability limits with fault injection
• Sensitivity Analyzer — Parameter sensitivity with tipping-point detection
• Mutation Tester — Verify safety policies catch real violations
• Safety Drill Runner — Automated readiness exercises
• Safety Benchmark — Standardized control benchmarks with latency stats
• What-If Analyzer — Explore configuration change impact
• Fleet Simulator — Interactive animated HTML fleet visualization

• Game Theory — Prisoner's Dilemma, Stag Hunt, Chicken for agent interactions
• Trust Propagation — Network trust with Sybil attack detection
• Swarm Analyzer — Emergent behavior detection in agent populations
• Consensus Protocol — Multi-agent voting with Byzantine fault tolerance
• Threat Correlator — Cross-module signal correlation with compound threat detection
• Attack Tree / Attack Graph — Threat modeling with choke-point analysis
• Goal Inference — Infer agent intentions from observed behavior
• Influence Propagation — Track how agents influence each other

• Incident Responder — Automated playbooks with severity-based routing
• Incident Forecaster — Predict future incidents from historical patterns
• Forensic Analyzer — Post-incident analysis with counterfactual reasoning
• Root Cause Analysis — 5 Whys, Fishbone, Fault Tree with cut-set analysis
• Postmortem Generator — Structured blameless postmortem documents
• War Room — Interactive HTML incident command dashboard
• Situational Awareness (SITREP) — DEFCON-style unified threat level reporting
• Containment Planner — Breach response strategy ranking
• Evidence Collector — Audit artifact collection for compliance

• Drift Detector — Behavioral drift with directional analysis
• Regression Detector — Safety metric regression between baselines
• Trend Tracker — Scorecard trends over time with regression alerts
• Adaptive Thresholds — Self-tuning safety thresholds with breach forecasting
• Safety Autopilot — Autonomous monitoring loop with corrective actions
• Alert Router — Rule-based routing with rate limiting and quiet hours
• Fatigue Detector — Alert fatigue analysis
• SLA Monitor — Check results against safety SLA targets
• Metrics Aggregator — Consolidated safety dashboard
• Fleet Overview — kubectl-style worker status

• Contract Templates — Pre-built contracts for common scenarios
• Contract Wizard — Interactive HTML builder for safe configs
• Contract Optimizer — Multi-objective parameter optimization
• Policy Linter — Detect misconfigurations and coverage gaps
• Safety Checklist — Customizable pre-deployment checklists
• Audit Trail — Tamper-evident hash-chained event logs
• Maturity Model — 8-dimension safety maturity assessment
• Culture Survey — Organizational AI safety culture evaluation
• Safety Quiz — Training quiz generation from knowledge base
• Red Team / Blue Team — Adversarial debate with judge verdict
• Tabletop Exercises — Structured scenario planning
• ROI Calculator — Cost-benefit analysis for safety controls

pip install ai-replication-sandbox

Or install from source:

git clone https://github.com/sauravbhattacharya001/ai.git
cd ai
pip install -e ".[dev]"

docker pull ghcr.io/sauravbhattacharya001/ai:latest
docker run --rm ghcr.io/sauravbhattacharya001/ai simulate --strategy greedy

from replication import Simulator, ScenarioConfig, Strategy

config = ScenarioConfig(
    max_workers=10,
    max_depth=3,
    rounds=50,
    strategy=Strategy.CAUTIOUS,
)
report = Simulator(config).run()
print(f"Peak workers: {report.peak_workers}")
print(f"Safety violations: {report.violations}")

from replication import SafetyScorecard, ScorecardConfig

scorecard = SafetyScorecard(ScorecardConfig())
result = scorecard.evaluate(simulation_report)
print(f"Overall grade: {result.grade}")
for dim in result.dimensions:
    print(f"  {dim.name}: {dim.score}/100")

from replication import ComplianceAuditor, AuditConfig, Framework

auditor = ComplianceAuditor(AuditConfig(
    frameworks=[Framework.NIST_AI_RMF, Framework.EU_AI_ACT]
))
result = auditor.audit(simulation_report)
for fw_result in result.framework_results:
    print(f"{fw_result.framework}: {fw_result.verdict}")

from replication import create_conservative_killswitch

ks = create_conservative_killswitch()
result = ks.evaluate(current_metrics)
if result.triggered:
    print(f"Kill switch activated: {result.strategy.kind}")

The unified CLI provides 100+ subcommands:

# Simulation & Analysis
python -m replication simulate --strategy greedy
python -m replication montecarlo --runs 500
python -m replication chaos --faults kill_worker,delay
python -m replication sensitivity --param max_depth
python -m replication what-if --param max_children=5

# Threat Detection
python -m replication killchain
python -m replication escalation
python -m replication covert-channels
python -m replication selfmod
python -m replication collusion

# Compliance & Governance
python -m replication compliance --framework nist_ai_rmf
python -m replication regulatory-map
python -m replication lint
python -m replication gate
python -m replication checklist

# Monitoring
python -m replication drift --window 20
python -m replication scorecard
python -m replication quick-scan
python -m replication sitrep

# Incident Response
python -m replication forensics
python -m replication root-cause
python -m replication postmortem
python -m replication warroom

# Interactive HTML Tools
python -m replication playground -o playground.html
python -m replication threat-matrix -o matrix.html
python -m replication fleet-sim -o fleet.html
python -m replication risk-heatmap -o heatmap.html
python -m replication radar -o radar.html

# Full list
python -m replication --list

src/replication/
├── contract.py          # Core contract engine
├── controller.py        # Replication controller & registry
├── worker.py            # Agent worker implementation
├── simulator.py         # Simulation engine
├── kill_switch.py       # Kill switch strategies
├── circuit_breaker.py   # Safety circuit breaker
├── killchain.py         # Kill chain analysis
├── escalation.py        # Privilege escalation detection
├── compliance.py        # Multi-framework compliance
├── forensics.py         # Post-incident forensics
├── game_theory.py       # Game-theoretic analysis
├── montecarlo.py        # Monte Carlo risk analysis
├── chaos.py             # Chaos/fault injection
├── ... (144 modules)    # See full docs
tests/                   # Comprehensive test suite
docs/                    # MkDocs documentation
demos/                   # Example scripts

Full documentation is available at sauravbhattacharya001.github.io/ai.

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure pytest and flake8 pass
5. Submit a pull request

Found a vulnerability? Please see our Security Policy for responsible disclosure.

This project is licensed under the MIT License — see LICENSE for details.