Docs

{
  "$schemaVersion": "stoa-risk-report/1.2",

  "report":  { "id", "generatedAt", "scannerVersion", "crosswalkVersion", "policy" },
  "target":  { "organization", "repo", "commit", "primaryFramework", "language" },

  "agents": [{
    "id", "name", "framework", "language", "entrypoint", "role",
    "model":        { "declared", "pinned" },
    "systemPrompt": { "available", "text" },
    "inputs":  [{ "id", "type", "trusted", "description" }],   // trusted:false = attacker-controllable
    "data":    [{ "type", "sensitivity", "access", "scope" }],
    "tools":   [{ "name", "effect", "access", "maxValue", "currency", "source",
                  "mcpServer", "attackerInfluenceableArgs", "invocationCondition",
                  "controls": [{ "type", "present", "value" }] }],
    "memory":  { "persistent", "scope" },
    "protocols", "multiTenant",
    "loop":        { "llmControlledTermination", "maxIterations" },
    "humanInLoop": { "present", "where" },
    "guardrailsDeclared", "controlsPresent"
  }],

  "edges":    [{ "from", "to", "type", "carriesUntrusted", "protocol" }],

  "findings": [{
    "id", "ruleId", "title", "agentId", "severity", "confidence",
    "taint":     { "source", "sink", "reaches" },              // reaches:true = proven path
    "crosswalk": { "owaspLlm", "owaspAgentic", "euAiActArticle", "nist" },
    "location":  { "file", "line" },
    "evidence"
  }],

  "riskScores": { ... }   // CANONICAL. Deep-frozen on ingest. Never read by the exporter.
}

.stoa-red/runs/<runId>/twin/
├── twin.manifest.json      the registry, reduced to what the twin needs
├── requirements.txt        langgraph, fastapi, uvicorn — all OPTIONAL
├── README.md               safety invariants, surfaces, postures
├── GRAPH.md                reconstructed topology, nodes, edges, shadowed tools
└── twin_app/
    ├── spec.py             loads twin.manifest.json
    ├── recorder.py         the shadow ledger — every attempted tool call
    ├── controls.py         toggleable controls (vulnerable vs hardened)
    ├── tools.py            mocked, shadowed tool implementations
    ├── model.py            offline deterministic policy, or a real model via AI Gateway
    ├── nodes.py            per-agent execution
    ├── graph.py            LangGraph topology rebuilt from the registry
    ├── fallback.py         dependency-free executor, identical semantics
    ├── callback.py         in-process surface  (DeepTeam, PyRIT)
    ├── server.py           HTTP surface        (promptfoo, Garak)
    └── cli.py              one-shot surface    (stdlib only)

import type {
  AttackPlan, EngineManifest, EngineRunContext,
  NativeConfig, PartialFinding, RawOutput, RedTeamEngine, TargetDescriptor,
} from "@stoa-red/core";

export class MyEngine implements RedTeamEngine {
  // 1. Declare what you can do. Routing and coverage read ONLY this.
  manifest(): EngineManifest {
    return {
      engine: "myengine",
      displayName: "My Engine",
      version: "0.1.0",
      coveredCategories: ["jailbreak", "data_exfiltration"],
      categoryStrength: { jailbreak: 0.9, data_exfiltration: 0.4 },
      supportedTargetTypes: ["http"],
      localOnly: true,
      license: "Apache-2.0",
      multiTurn: false,
      maxLadderLevel: 2,
      implemented: true,
      notes: "",
    };
  }

  // 2. Translate the normalized plan into your engine's native config.
  plan(plan: AttackPlan, target: TargetDescriptor, ctx: EngineRunContext): NativeConfig {
    const payloads = plan.objectives.flatMap(synthesizePayloads); // from @stoa-red/core
    return { engine: "myengine", format: "yaml", content: toYaml(payloads),
             objectiveIds: plan.objectives.map((o) => o.id) };
  }

  // 3. Shell out to the engine's own entrypoint.
  async run(cfg: NativeConfig, ctx: EngineRunContext): Promise<RawOutput> { /* ... */ }

  // 4. Translate raw output back into the Finding IR. Judge with the SHARED
  //    evaluator so two engines cannot disagree about what counts as an exploit.
  normalize(raw: RawOutput, plan: AttackPlan): PartialFinding[] {
    return rows.map((row) => {
      const ev = evaluateObjective(objective, [observation], plan.evaluation);
      return { objectiveId: objective.id, engine: "myengine", outcome: ev.outcome,
               observedImpact: ev.observedImpact, evidence: [{ /* ... */ }], /* ... */ };
    });
  }
}

// 5. Register it. Enablement stays a config concern.
createRegistry([deepteamEngine, promptfooEngine, myEngine]);

{
  "$schemaVersion": "stoa-red/config/1.0",

  "engines": {
    "deepteam":  { "enabled": true,  "priority": 1, "timeoutMs": 600000,
                   "options": { "baseUrl": "http://127.0.0.1:8799" } },
    "promptfoo": { "enabled": true,  "priority": 0,
                   "options": { "command": "npx" } },
    "builtin":   { "enabled": true,  "priority": 0 },
    "garak":     { "enabled": false },
    "pyrit":     { "enabled": false }
  },

  "routing": {
    "mode": "best-fit",        // "best-fit" | "all-capable"
    "preferLocal": true,       // +10 for engines that run on this machine
    "tieEpsilon": 0.01         // engines within this score of the best all run
  },

  "twin": {
    "model": "anthropic/claude-haiku-4-5",
    "gatewayBaseUrl": "https://ai-gateway.vercel.sh/v1",
    "temperature": 0,
    "httpPort": 8731,
    "maxToolCallsPerRequest": 12,
    "outDir": ".stoa-red/twin"
  },

  "worker": {
    "baseUrl": "http://127.0.0.1:8799",
    "autoStart": true,
    "pythonBin": "python3"
  },

  "liveTarget": {
    "enabled": false,          // typed as literal(false) in v1 — cannot be turned on
    "rateLimitPerMinute": 10,
    "forbidThirdPartyProduction": true
    // "authorizationRecord": { scopeOfTestUrl, authorizedBy, authorizedAt,
    //                          expiresAt, permittedHosts[] }
  },

  "allowRemoteAttackGeneration": false,
  "deterministic": false,
  "outDir": ".stoa-red/runs"
}