AgentShield API Reference

This document separates the currently supported automation surfaces from internal contributor modules.

Support Levels

Stable for users

• CLI: agentshield scan, agentshield init, agentshield miniclaw start
• Scanner JSON output: agentshield scan --format json
• MiniClaw package API: ecc-agentshield/miniclaw
• MiniClaw HTTP API: /api/* endpoints exposed by startMiniClaw()

Internal for contributors

• src/scanner/index.ts
• src/reporter/score.ts
• src/reporter/index.ts
• src/rules/*

These source modules are useful inside the repository, but the npm package root export currently points to the CLI entrypoint. Treat them as implementation details unless the package exports change.

Contributor Scanner Modules

These are the source-level entrypoints contributors use inside this repository today.

They are documented here for extension work and tests, not as stable npm import paths.

src/scanner/index.ts

interface ScanResult {
  target: ScanTarget;
  findings: Finding[];
}

function scan(targetPath: string): ScanResult;
function discoverConfigFiles(targetPath: string): ScanTarget;

• discoverConfigFiles() finds Claude/AgentShield-relevant files under a target path
• scan() runs built-in rules against the discovered files and returns sorted findings

src/reporter/score.ts

function calculateScore(result: ScanResult): SecurityReport;

• wraps findings with timestamp, summary counts, and numeric/category scoring

src/reporter/index.ts

function renderTerminalReport(report: SecurityReport): string;
function renderJsonReport(report: SecurityReport): string;
function renderMarkdownReport(report: SecurityReport): string;
function renderHtmlReport(report: SecurityReport): string;

• reporters consume a SecurityReport
• renderJsonReport() returns formatted JSON text
• renderMarkdownReport() and renderHtmlReport() also expose runtimeConfidence when present on findings
• renderHtmlReport() includes an executive summary with risk posture, priority findings, and category exposure

CLI API

Primary commands:

agentshield scan [options]
agentshield init
agentshield miniclaw start [options]

High-value scan options:

• --format terminal|json|markdown|html|sarif
• --output <path> for writing the selected report format to a file
• --fix
• --opus
• --stream
• --injection
• --sandbox
• --taint
• --deep
• --corpus
• --supply-chain
• --supply-chain-online
• --policy <path>
• --evidence-pack <dir>
• --no-evidence-redact
• --min-severity critical|high|medium|low|info
• --log <path>
• --log-format ndjson|json

--corpus runs the built-in attack corpus as a regression benchmark and reports category coverage plus whether the gate is ready for continuous rule hardening.

Policy preset generation:

agentshield policy init --pack enterprise --owner security@example.com
agentshield policy init --pack regulated --name "Regulated Agent Policy"
agentshield policy export --pack ci-enforcement --output-dir .github/agentshield-policies
agentshield policy promote --manifest .github/agentshield-policies/manifest.json --pack ci-enforcement --output .agentshield/policy.json
agentshield policy promote --manifest .github/agentshield-policies/manifest.json --pack ci-enforcement --dry-run --json

Supported packs: oss, team, enterprise, regulated, high-risk-hooks-mcp, and ci-enforcement.

policy promote is checksum-first: it rejects missing manifests, unsupported manifest schemas, ambiguous multi-pack manifests without --pack, tampered policy files whose SHA-256 no longer matches the manifest, and policy files that fail the organization policy schema. This makes exported policy bundles usable as reviewable CI artifacts before they become the active .agentshield/policy.json.

The GitHub Action exposes the same organization policy gate through the policy input. It reports policy-status and policy-violations outputs, adds policy results to the job summary, emits policy violations into SARIF as agentshield-policy/* code-scanning results when SARIF output is enabled, and fails on non-compliance by default. Set fail-on-policy: "false" to collect policy evidence without failing the workflow.

The GitHub Action also exposes baseline drift through the baseline and save-baseline inputs. It reports baseline-path, baseline-status, new-findings, resolved-findings, unchanged-findings, and score-delta outputs, appends a baseline drift block to the job summary, and emits annotations for newly introduced findings. Set fail-on-findings: "false" when the workflow should fail only on baseline drift instead of every current finding.

The GitHub Action runs offline MCP package supply-chain verification by default through the supply-chain input. It reports supply-chain-status, supply-chain-risky-packages, supply-chain-critical-count, and supply-chain-high-count outputs, appends package-risk evidence to the job summary, and fails on critical/high package risk whenever fail-on-findings is enabled. Set fail-on-supply-chain: "false" to collect evidence only, set it to "true" to force the package-risk gate in evidence-only workflows, or enable supply-chain-online: "true" to add npm registry metadata.

Policy files use schema version 1. Enterprise policy metadata is optional but recommended for CI gates:

• policy_pack: oss, team, enterprise, regulated, high-risk-hooks-mcp, or ci-enforcement
• owners: policy owner identifiers for audit and escalation
• exceptions: temporary rule exceptions with id, rule, owner, reason, expires_at, optional scope, optional severity, and optional ticket

Expired exceptions are reported as policy violations. Active exceptions suppress only matching policy violations and are printed in the policy evaluation output.

Exit codes:

• 0: scan completed without critical findings
• 1: CLI usage error or runtime failure
• 2: scan completed and at least one critical finding was reported

Structured scan logs:

interface ScanLogEntry {
  timestamp: string;
  level: "info" | "warn" | "error" | "debug";
  phase: string;
  message: string;
  data?: Record<string, unknown>;
}

Scanner Report JSON

The supported machine-readable scanner contract today is the JSON report returned by:

agentshield scan --format json

Baseline comparison output is treated as auxiliary output. When JSON or SARIF is written to stdout, baseline save/compare and gate text is written to stderr so the primary machine-readable report remains parseable.

Scanner JSON also includes harnessAdapters when report generation runs through scan(). This field records deterministic local marker evidence for supported harnesses such as Claude Code, OpenCode, Codex, Gemini, dmux, generic terminal agents, and project-local templates. It is local/free scan evidence only; it does not call hosted services or require a paid/team entitlement.

Baseline snapshot creation is available as a first-class CLI command:

agentshield baseline write --path .claude --output .github/agentshield-baseline.json

Add --json to emit parseable metadata with baselinePath, targetPath, score, grade, findings, and minSeverity.

Evidence packs are available through:

agentshield scan --evidence-pack ./agentshield-evidence

The evidence-pack directory is deterministic and contains manifest.json, README.md, agentshield-report.json, agentshield-report.html, agentshield-results.sarif, policy-evaluation.json, baseline-comparison.json, supply-chain.json, ci-context.json, and remediation-plan.json. In the GitHub Action, evidence packs use the same supply-chain verification result that powers the package-risk outputs instead of an empty placeholder. Local path, username, email, and token-shaped string redaction is enabled by default.

Consumers can verify and read back a saved pack:

agentshield evidence-pack verify ./agentshield-evidence --json
agentshield evidence-pack inspect ./agentshield-evidence --json
agentshield evidence-pack fleet ./repo-a-evidence ./repo-b-evidence --json

inspect verifies the bundle first, then emits score, finding counts, runtime-confidence counts, policy status, baseline drift status, supply-chain counts, CI provenance, and remediation workflow counts for GitHub App, Linear, or customer-review ingestion.

fleet runs the same inspection across multiple evidence-pack directories and emits totals plus route suggestions: invalid, security-blocker, policy-review, baseline-regression, supply-chain-review, or ready. Fleet output includes operatorReadback.approvalIds; each non-ready reviewItems[] entry repeats its approvalId and exposes ticket.externalId in the form agentshield-fleet-review:<approvalId> for idempotent GitHub App or Linear sync.

Top-level shape:

interface SecurityReport {
  timestamp: string;
  targetPath: string;
  findings: Finding[];
  score: SecurityScore;
  summary: ReportSummary;
}

Finding shape:

interface Finding {
  id: string;
  severity: "critical" | "high" | "medium" | "low" | "info";
  category:
    | "secrets"
    | "permissions"
    | "hooks"
    | "mcp"
    | "agents"
    | "injection"
    | "exposure"
    | "exfiltration"
    | "misconfiguration";
  title: string;
  description: string;
  file: string;
  line?: number;
  evidence?: string;
  runtimeConfidence?:
    | "active-runtime"
    | "project-local-optional"
    | "template-example"
    | "docs-example"
    | "plugin-manifest"
    | "hook-code";
  fix?: {
    description: string;
    before: string;
    after: string;
    auto: boolean;
  };
}

runtimeConfidence

runtimeConfidence is emitted when AgentShield can distinguish active runtime config from lower-confidence source kinds such as project-local settings, templates/examples, declarative manifests, and manifest-resolved non-shell hook implementations.

• active-runtime: active config such as mcp.json, .claude/mcp.json, .claude.json, or active settings.json
• project-local-optional: project-local files such as settings.local.json
• template-example: template or catalog files such as mcp-configs/, config/mcp/, or configs/mcp/
• docs-example: docs/tutorial/example config such as docs/guide/settings.json or commands/*.md
• plugin-manifest: declarative hook manifests such as hooks/hooks.json
• hook-code: manifest-resolved non-shell implementations such as scripts/hooks/session-start.js

Current caveat:

• report output now distinguishes example docs, plugin manifests, and non-shell hook implementations from active runtime findings
• scoring discounts non-secret template-example findings to 0.25x and caps them at 10 deduction points per file and score category to reduce template-catalog inflation
• scoring discounts non-secret docs-example findings to 0.25x to reduce example-config inflation
• scoring discounts non-secret project-local-optional findings to 0.75x to reduce project-local score inflation
• scoring discounts non-secret plugin-manifest findings to 0.5x to reduce declarative-manifest inflation
• hook-code findings currently keep full weight, but the active rules there are still narrow language-aware implementation signals
• committed real secrets still count at full weight even inside template files
• docs-only example trees now re-add the standalone CLAUDE.md example file for scanning, while the rest of the nested subtree stays suppressed unless a runtime companion exists
• example bundles outside the current docs/, commands/, examples/, samples/, demo/, tutorial/, guide/, cookbook/, and playground/ path heuristics can still be treated as live config until broader example-root classification lands

Concrete examples:

• docs-example: docs/guide/settings.json or docs/guide/CLAUDE.md when that subtree has a runtime companion
• plugin-manifest: hooks/hooks.json
• hook-code: scripts/hooks/session-start.js

For the current false-positive and scoring follow-up queue, see false-positive-audit.md, especially Pattern Signatures In Recent Alerts, Common Noisy File Archetypes, and Triage Rules For Current Reports.

MiniClaw Package API

MiniClaw is the stable programmatic API exposed by this package today:

import {
  startMiniClaw,
  createMiniClawSession,
  routePrompt,
  createSafeWhitelist,
  createGuardedWhitelist,
  createCustomWhitelist,
  createMiniClawServer,
} from "ecc-agentshield/miniclaw";

High-value entrypoints:

• startMiniClaw(config?): start the MiniClaw HTTP server with secure defaults
• createMiniClawSession(config?): create an isolated sandbox session for embedding MiniClaw into an existing app
• routePrompt(request, session): sanitize and process a prompt against a session
• createSafeWhitelist(), createGuardedWhitelist(), createCustomWhitelist(): build tool policy sets
• createMiniClawServer(config): create a server handle without the convenience wrapper

Current packaging caveat:

• the React dashboard source exists at src/miniclaw/dashboard.tsx
• there is not yet a published ecc-agentshield/miniclaw/dashboard subpath export
• if you want the dashboard today, vendor the source component from the repository instead of importing a non-existent subpath

Core MiniClaw types are exported from ecc-agentshield/miniclaw, including:

• PromptRequest
• PromptResponse
• MiniClawSession
• MiniClawConfig
• SandboxConfig
• SecurityEvent

For the complete MiniClaw architecture notes, see src/miniclaw/README.md.

MiniClaw HTTP API

Endpoints exposed by the built-in server:

Method	Endpoint	Description
POST	/api/session	Create a new sandboxed session
GET	/api/session	List active sessions
DELETE	/api/session/:id	Destroy a session and clean up its sandbox
POST	/api/prompt	Submit a prompt for a session
GET	/api/events/:sessionId	Read security events for a session
GET	/api/health	Health check

Create-session response:

{
  "sessionId": "uuid",
  "createdAt": "2026-03-13T19:42:00.000Z",
  "allowedTools": ["read", "search", "list"],
  "maxDuration": 300000
}

List-sessions response:

{
  "sessions": [
    {
      "id": "uuid",
      "createdAt": "2026-03-13T19:42:00.000Z",
      "allowedTools": ["read", "search", "list"],
      "maxDuration": 300000
    }
  ]
}

Prompt request:

{
  "sessionId": "uuid",
  "prompt": "Read src/index.ts",
  "context": {
    "traceId": "optional"
  }
}

Prompt response:

{
  "sessionId": "uuid",
  "response": "File contents: ...",
  "toolCalls": [
    {
      "tool": "read",
      "args": {
        "path": "src/index.ts"
      },
      "result": "...",
      "duration": 14
    }
  ],
  "duration": 1234,
  "tokenUsage": {
    "input": 100,
    "output": 200
  }
}

Error format:

{
  "error": "Rate limit exceeded. Please try again later."
}

Additional responses:

{
  "sessionId": "uuid",
  "events": [
    {
      "type": "prompt_injection_detected",
      "details": "Removed hidden instruction",
      "timestamp": "2026-03-13T19:42:01.000Z",
      "sessionId": "uuid"
    }
  ]
}

{
  "status": "ok",
  "sessions": 1
}