Agent Capability Engine

Tiếng Việt · English

Compile an AI-agent system into a deterministic capability graph. Query every reachable effect. Gate dangerous changes before execution. Add ForgeOS runtime evidence to move from possible to selected, enforced, observed, and proven.

Agent Capability Engine (agentcap) is a production-oriented, local-first graph and policy engine for AI-agent repositories. It discovers instruction sources, agents, skills, MCP servers, tools, controls, secret references, runtime receipts, and critical assets without executing repository code or calling an LLM.

It is useful as a standalone scanner and CI gate. When connected to ForgeOS, it also consumes verified RoutePlans, execution receipts, evidence records, and security reports so the graph reflects runtime truth rather than static possibility alone.

At a glance

Graph, not guesswork: compile explicit authority into deterministic nodes and edges, then preserve the shortest evidence path for each result.
Policy before execution: query and gate dangerous paths without running repository code or invoking an LLM.
Runtime-aware by design: verified ForgeOS documents raise certainty only where an actual route, policy decision, receipt, or evidence record supports it.

Architecture at a glance

repository + optional ForgeOS documents → bounded scanners / adapters → canonical capability graph
                                                                                 ↓
                    query, policy, diff, report, SARIF, DOT, Mermaid, and loopback API

The static compiler and ForgeOS bridge share one normalized fact model, so the same policy can distinguish an unproven possibility from observed or proven runtime evidence. See architecture and ForgeOS integration for the contract boundaries.

The core idea

Agent configuration is executable authority.

A small change to an instruction file, skill, hook, MCP server, route, permission profile, or evidence rule can silently expand what an untrusted input may influence. Traditional dependency scanners do not model that path.

agentcap answers:

What instruction sources, agents, skills, tools, controls, secrets, and assets exist?
Can an untrusted source reach a critical effect?
Which exact edges form the shortest witness path?
Did a pull request create a new dangerous path?
Did an edge regress from blocked or proven back to possible?
Which ForgeOS route, receipt, evidence record, or surface report changed runtime certainty?

Standalone and ForgeOS-connected modes

Capability	Standalone `agentcap`	`agentcap` + ForgeOS
Static repository discovery	Yes	Yes
Deterministic capability graph	Yes	Yes
Shortest dangerous-path query	Yes	Yes
Policy and CI gate	Yes	Yes
Blast-radius diff	Yes	Yes
Route selection visibility	No	Yes
Tool enforcement result	Unproven	Yes
Execution receipts	No	Yes
Evidence-backed completion	No	Yes
Runtime state overlay	Normalized facts only	Native ForgeOS documents

The separation is deliberate:

Agent Capability Engine                 ForgeOS
─────────────────────────────────       ─────────────────────────────
static capability compilation           technique/provider selection
reachability and shortest witness        context construction
policy and CI gates                      permissions and approvals
snapshot diff                            tool execution and recovery
portable reports                         receipts and evidence decisions

Neither project imports the other's business logic. The integration is document-based and versioned.

Why combine it with ForgeOS?

A static scanner can prove that a path is structurally reachable. It cannot prove that an unrelated runtime actually selected, blocked, executed, receipted, or verified that path.

ForgeOS supplies those missing runtime facts.

possible < declared < routable < selected < allowed
         < observed < receipted < proven < blocked/denied

Runtime state is monotonic. Out-of-order delivery cannot downgrade a stronger state.

Example:

Static graph:
repository instruction
  → deploy skill
  → shell tool
  → production environment
State: possible

With ForgeOS runtime evidence:
repository instruction
  → deploy skill
  → shell tool
  → production environment
State: blocked
Policy: repository content cannot authorize deployment

Production properties

One Go binary with no external Go module dependency.
Zero-token and offline by default.
Deterministic snapshots and content hashes.
Strict validation at snapshot, fact, policy, report, and runtime boundaries.
Explicit limits for file count, file size, depth, graph size, fact count, policy size, API query size, and path traversal.
Secret names may be recorded; secret values are never copied.
Atomic durable output replacement on Unix and Windows.
Loopback-only HTTP API with hardened security headers.
Stable CI exit codes.
Backward-readable capability-graph/v1 and capability-facts v1 formats.
Structured ForgeOS v0.6.1 parser instead of keyword-only inference.
Canonical self-hash verification for ForgeOS runtime documents.

Install

Download a release binary

Release assets are produced for:

Windows amd64
Linux amd64
macOS amd64
macOS arm64

Each release bundle includes SHA-256 checksums, SPDX 2.3 SBOM metadata, schemas, examples, and build provenance.

Build from source

The source supports Go 1.23 and later. Official release builds pin Go 1.26.5.

go build -trimpath \
  -ldflags="-s -w -X github.com/casioreview20-glitch/agent-capability-engine/internal/model.ToolVersion=1.0.2" \
  -o agentcap ./cmd/agentcap

No module dependency download is required by this repository.

Quick start

# Compile a repository into an immutable snapshot.
agentcap scan . --out .agentcap/static.json

# Find a concrete path from untrusted input to production.
agentcap path \
  --snapshot .agentcap/static.json \
  --from trust=untrusted \
  --to environment=production

# Enforce a JSON or bounded-YAML policy.
agentcap gate \
  --snapshot .agentcap/static.json \
  --policy agentcap-policy.yaml

# Create a self-contained offline report.
agentcap report \
  --snapshot .agentcap/static.json \
  --out agentcap-report.html

Validate a real GitHub repository with ForgeOS

This is the recommended production validation workflow. It keeps the target repository, ForgeOS, and the analysis engine separate while joining them through signed or self-addressed documents.

1. Pin the repositories

Always test immutable commits, not moving branches.

git clone <target-repository-url> target-repo
git -C target-repo checkout <target-commit-sha>

git clone https://github.com/casioreview20-glitch/forge-os forge-os
git -C forge-os checkout <forgeos-commit-or-release>

Record both commit SHAs in the validation evidence.

2. Create the target baseline

agentcap scan ./target-repo \
  --out .agentcap/target-static.json \
  --format json

agentcap doctor \
  --snapshot .agentcap/target-static.json \
  --root ./target-repo

Run the initial gate before ForgeOS contributes runtime facts:

agentcap gate \
  --snapshot .agentcap/target-static.json \
  --policy agentcap-policy.yaml

A static FAIL is not necessarily a runtime exploit. It means a bounded witness path exists under the available facts.

3. Compile ForgeOS itself

agentcap scan ./forge-os \
  --out .agentcap/forgeos-static.json \
  --format json

When the repository identifies itself as ForgeOS and contains Capability Graph v2, agentcap reads the structured contracts directly:

outcomes, techniques, providers, evaluators, and reviewed relations;
skills-v2/catalog.json;
policy profiles;
MCP registry sources and MCP configuration;
harness profiles;
adapter and platform TCK declarations.

Malformed typed ForgeOS contracts fail the scan. They are not silently downgraded to keyword inference.

4. Ask ForgeOS to route a real validation task

Run ForgeOS against a concrete, bounded task for the selected repository. For example:

node ./forge-os/src/cli/forge.mjs route \
  --query "Audit the pinned target repository for untrusted-input paths to shell, secret, network, or production effects. Require evidence for every conclusion." \
  --domain cybersecurity \
  --json > .agentcap/route-output.json

The exact ForgeOS command may vary by release. agentcap ingest accepts a RoutePlan v2 document directly or the standard ForgeOS CLI envelope containing routePlan.

5. Ingest verified ForgeOS runtime documents

agentcap ingest \
  --snapshot .agentcap/forgeos-static.json \
  --facts .agentcap/route-output.json \
  --out .agentcap/forgeos-routed.json

During actual execution, collect and ingest supported runtime artifacts:

RoutePlan schema v2;
MCP execution receipt schema v1;
harness event receipt schema v1;
evidence records;
agent-surface report schema v1;
normalized capability-facts NDJSON.

agentcap ingest \
  --snapshot .agentcap/forgeos-routed.json \
  --facts .agentcap/runtime-documents.json \
  --out .agentcap/forgeos-runtime.json

Self-addressed ForgeOS documents are canonicalized and verified. A document with valid-looking fields but a mismatched hash is rejected.

6. Connect runtime truth to target-repository nodes

ForgeOS integrations may emit portable capability facts using stable node IDs from the target snapshot:

{"kind":"edge_state","from":"source:repository-readme","to":"tool:shell.execute","relation":"may_influence","state":"blocked","properties":{"policy":"repository-content-cannot-authorize-shell"}}

Ingest those facts into the target snapshot:

agentcap ingest \
  --snapshot .agentcap/target-static.json \
  --facts .agentcap/target-runtime.ndjson \
  --out .agentcap/target-runtime.json

Only emit blocked, receipted, or proven after ForgeOS actually enforced or verified that state. Never fabricate strong runtime states merely to make a policy pass.

7. Gate, diff, and report

agentcap gate \
  --snapshot .agentcap/target-runtime.json \
  --policy agentcap-policy.yaml

agentcap diff \
  --base .agentcap/target-static.json \
  --head .agentcap/target-runtime.json

agentcap report \
  --snapshot .agentcap/target-runtime.json \
  --out .agentcap/target-runtime-report.html

For pull requests, compare the pinned baseline with the new commit:

agentcap scan ./target-repo \
  --out .agentcap/head.json

agentcap diff \
  --base .agentcap/baseline.json \
  --head .agentcap/head.json \
  --gate

What makes the combined test stronger?

The combined workflow produces three distinct evidence layers:

Static capability truth — what the repository structure permits or implies.
Runtime control truth — what ForgeOS selected, allowed, blocked, or executed.
Evidence truth — what receipts and evaluators can defensibly prove.

A complete validation record should retain:

target repository URL and immutable commit SHA;
ForgeOS commit or release;
agentcap version;
static snapshot content hash;
policy file and policy hash;
RoutePlan ID and canonical hash;
receipt and evidence identifiers;
runtime snapshot content hash;
gate, diff, and report outputs.

This makes the test repeatable and auditable instead of relying on screenshots or an agent's natural-language claim.

CLI

agentcap scan [root]
  [--out snapshot.json]
  [--max-files N]
  [--max-bytes N]
  [--max-depth N]
  [--best-effort]
  [--format text|json]

agentcap path
  --snapshot snapshot.json
  --from key=value[,key=value]
  --to key=value[,key=value]
  [--max-depth N]
  [--max-visited N]
  [--include-blocked]
  [--format text|json]

agentcap query
  --snapshot snapshot.json
  --selector key=value[,key=value]
  [--limit N]
  [--format json|ndjson|text]

agentcap gate --snapshot snapshot.json --policy policy.json|policy.yaml
agentcap diff --base base.json --head head.json [--gate]
agentcap ingest --snapshot base.json --facts runtime.json|runtime.ndjson --out updated.json
agentcap report --snapshot snapshot.json [--out report.html]
agentcap export --snapshot snapshot.json --format json|dot|mermaid|sarif|html [--out file]
agentcap doctor [--snapshot snapshot.json] [--root repository] [--policy policy.yaml]
agentcap serve --snapshot snapshot.json [--addr 127.0.0.1:7777]
agentcap version

Selectors support id, kind, name, or an exact property:

id=agent:forgeos-router
kind=technique
trust=untrusted
environment=production
kind=tool,effect=process.execute

Stable exit codes

Code	Meaning
`0`	Command succeeded or policy passed
`1`	Policy violation, diff regression, or new critical path
`2`	Invalid command, option, policy, facts, or runtime document
`3`	Analysis incomplete, result truncated, or policy unknown
`4`	Internal, persistence, or I/O failure

Policy

JSON is strict. YAML uses an intentionally small two-space dialect: no aliases, tags, flow collections, tabs, or multiline scalars.

version: 1

defaults:
  maxDepth: 32
  maxVisited: 100000
  includeBlocked: false
  excludeStates:
    - denied

deny:
  - id: untrusted-to-production
    description: Untrusted instructions must not reach production
    from:
      properties:
        trust: untrusted
    to:
      properties:
        environment: production
    unless:
      edgeRelation: human_approved

A result is:

FAIL when a bounded witness path exists.
PASS when all rule endpoints exist and no witness path exists.
UNKNOWN when endpoints are absent or a traversal limit prevents a defensible decision.

Schemas are available in spec/.

Diff and CI gate

agentcap diff \
  --base .agentcap/baseline.json \
  --head .agentcap/head.json \
  --gate

The gate fails when the head snapshot adds a previously unreachable critical path or downgrades an edge's safety/certainty state, including blocked → possible and proven → possible.

Example GitHub Actions step:

- name: Compile capability graph
  run: go run ./cmd/agentcap scan . --out .agentcap/head.json

- name: Reject capability regressions
  run: go run ./cmd/agentcap diff --base .agentcap/baseline.json --head .agentcap/head.json --gate

Review and commit a baseline only when the capability expansion is intentional.

Local API and offline report

agentcap serve \
  --snapshot .agentcap/static.json \
  --addr 127.0.0.1:7777

The server intentionally refuses non-loopback addresses.

GET|HEAD /
GET|HEAD /healthz
GET|HEAD /api/v1/snapshot
GET|HEAD /api/v1/nodes?selector=kind=tool&limit=100
GET|HEAD /api/v1/path?from=trust=untrusted&to=environment=production

Requests with bodies, unsupported methods, oversized query strings, invalid selectors, or out-of-range traversal limits are rejected.

Export formats:

agentcap export --snapshot graph.json --format json
agentcap export --snapshot graph.json --format dot --out graph.dot
agentcap export --snapshot graph.json --format mermaid --out graph.mmd
agentcap export --snapshot graph.json --format sarif --out agentcap.sarif
agentcap export --snapshot graph.json --format html --out report.html

The HTML report is self-contained and uses no network asset.

Scanner behavior

The generic scanner recognizes:

instruction sources such as README.md, AGENTS.md, CLAUDE.md, and Copilot instructions;
agent, skill, adapter, hook, evidence, capability, config, and schema surfaces;
MCP JSON configuration;
environment-variable references;
shell, network, filesystem, Git, and production effects.

It does not execute repository code, shell commands, package scripts, plugins, or MCP servers. It also does not clone repositories; pin and clone the target separately.

Use .agentcapignore for generated or intentionally excluded paths:

fixtures/generated/**
private-tests/**

Negation patterns are intentionally unsupported. Symlinks are not followed.

Strict mode fails on malformed relevant files. --best-effort isolates parser failures, marks the snapshot incomplete, and records bounded diagnostics. File, depth, and size omissions also produce diagnostics.

Security boundary

agentcap is an analysis and gating engine, not an agent runtime. It can establish graph reachability under its input facts; it cannot prove that an unrelated runtime enforces the claimed policy. ForgeOS supplies the deepest enforcement and evidence overlay.

Read SECURITY.md before exposing reports or snapshots. Although secret values are never intentionally stored, node names, file paths, secret identifiers, and capability topology can still be sensitive metadata.

Architecture

Repository / ForgeOS documents
            │
            ▼
      adapters and parsers
            │
            ▼
       normalized facts
            │
            ▼
 deterministic graph snapshot
            │
   ┌────────┼─────────┐
   ▼        ▼         ▼
 path     policy     diff
 engine   engine     engine
   │        │         │
   └────────┼─────────┘
            ▼
  CLI / CI / API / reports

Core packages do not depend on the UI, ForgeOS business logic, or a graph database. See docs/architecture.md and docs/forgeos-integration.md.

Development and verification

make verify
make fuzz-smoke
make release VERSION=1.0.2

Core verification:

gofmt -w ./cmd ./internal
go vet ./...
go test -count=1 ./...
go test -race -count=1 ./...

See CONTRIBUTING.md, CHANGELOG.md, and SECURITY.md.

Current boundaries

Static reachability is not proof of exploitation.
A PASS is only as strong as the supplied facts, policy, and traversal limits.
ForgeOS runtime documents strengthen the result only after their schemas and self-hashes verify.
agentcap does not run arbitrary target code or perform penetration testing.
Cross-repository runtime edges must be emitted by a trusted integration using stable target node IDs.
Reports are local-first, but their metadata may still be sensitive.

These boundaries are intentional. The project prefers UNKNOWN or a rejected document over a confident but unsupported claim.

License

MIT. See LICENSE.

FilesExpand file tree

README.md

Latest commit

History