Quick Reference¶

Purpose: Fast lookup for AI agents - commands, patterns, exit codes, and common operations. Support and version authority: Product Support and installation.

TL;DR - What is Assay?¶

Assay = an open evidence profile for privileged MCP tool actions, with a reference enforcing proxy. - Input: Policy decisions, observations, evidence bundles and bounded external receipts - Output: Offline-verifiable evidence and derived Trust Basis/Card, SARIF/JUnit/CI projections - Boundary: An allow is not proof of a provider action; imported claims do not become verified outcomes. See ADR-042.

Most Common Commands¶

# First-time setup
assay init                    # Generate eval.yaml + policy.yaml
assay init --ci               # Also generate GitHub workflow

# Validate traces
assay validate --config eval.yaml --trace-file traces.jsonl
assay run --config eval.yaml --trace-file traces.jsonl

# CI gate (strict mode)
assay ci --config eval.yaml --trace-file traces.jsonl

# Trust compiler artifacts
assay evidence verify bundle.tar.gz
assay trust-basis generate bundle.tar.gz --out trust-basis.json
assay trust-card generate bundle.tar.gz --out-dir trustcard
# writes trustcard.json, trustcard.md, and static trustcard.html

# Debug failures
assay doctor                  # Diagnose common issues
assay explain --trace traces.jsonl --policy policy.yaml  # Explain violations

The explain example requires inputs accepted by that command's trace and policy parser. It is not a drop-in recovery for every wrapper policy: the MCP quickstart policy's schemas section is not accepted by explain. Do not remove constraints to make a policy parse or infer that this reproduces the wrapper's decision.

Evaluation Exit Codes¶

This is an evaluation-oriented summary, not a universal interpretation of every command's process status. Read the command's typed result as well: doctor can exit zero with unavailable capabilities; MCP request errors are not process exits.

Migration note: Use --exit-codes=v2 (default) or --exit-codes=v1 for legacy behavior.

DX Note: assay ci treats Report IO failures (JUnit/SARIF writing) as Warnings (checks strictly pass), ensuring robust pipelines. Diagnostics are injected into run.json warnings.

Reason Code Registry¶

Config Errors (exit 2)¶

Parse a Run argv: JSON array and pass its elements directly to a process API. Never join caller-controlled path elements into a shell command.

Infra Errors (exit 3)¶

Test Failures (exit 1)¶

Run / CI Output (PR gate, PR #159)¶

After assay run or assay ci:

Seeds are decimal strings or null (no JSON number) for JS/TS precision safety. See Run Output and SPEC-PR-Gate-Outputs-v1.

File Locations¶

GitHub Action Usage¶

# Recommended (v3 action)
- uses: Rul1an/assay-action@v3
  with:
    fail_on: error      # error | warn | info | none
    sarif: true         # Upload to Security tab
    comment_diff: true  # PR comment on findings

# Alternative (CLI only)
- run: |
    assay ci \
      --config ci-eval.yaml \
      --trace-file traces/ci.jsonl \
      --junit .assay-reports/junit.xml \
      --sarif .assay-reports/sarif.json

Policy Quick Reference¶

# Full McpPolicy for assay_check_args / assay_check_sequence
version: "1"

tools:
  filesystem_read:
    args:
      path:
        type: string
        pattern: "^/allowed/.*"

  http_request:
    args:
      url:
        blocklist:
          - "*.internal.*"

sequences:
  - name: auth_before_data
    pattern: [authenticate, fetch_data]
    required: true

# Name-only compatibility dialect for assay_policy_decide
# Exact string membership; wildcard-looking names stay literal.
# Do not add tools, allow, or deny here — that is E_POLICY_PARSE.
blocklist:
  - "rm_rf"
  - "drop_database"

Trace Format¶

{"tool": "filesystem_read", "args": {"path": "/tmp/file.txt"}, "result": "contents..."}
{"tool": "http_request", "args": {"url": "https://api.example.com"}, "result": {"status": 200}}

Python SDK Quick Start¶

from assay import AssayClient, Coverage, validate

# Record traces
client = AssayClient("traces.jsonl")
client.record_trace({"tool": "read_file", "args": {"path": "/tmp/x"}})

# Validate
result = validate("policy.yaml", traces)
assert result["passed"]

# Coverage analysis
coverage = Coverage.analyze(traces, min_coverage=80.0)
print(f"Coverage: {coverage.score}%")

MCP Server Quick Start¶

# Start MCP proxy with policy enforcement
assay mcp wrap \
  --policy policy.yaml \
  --decision-log decisions.jsonl \
  --event-source "assay://myapp"

# Dry-run mode (log but don't block)
assay mcp wrap --policy policy.yaml --dry-run

Evidence Commands¶

# Export bundle from profile
assay evidence export --profile profile.yaml --out bundle.tar.gz

# Verify bundle integrity
assay evidence verify bundle.tar.gz

# Lint for security issues (SARIF output)
assay evidence lint bundle.tar.gz --format sarif

# Compare two bundles
assay evidence diff baseline.tar.gz current.tar.gz

Tool Signing¶

# Generate keypair
assay mcp tool keygen --out keys/

# Sign tool definition
assay mcp tool sign tool.yaml --key keys/private.pem --out tool-signed.yaml

# Verify signature
assay mcp tool verify tool-signed.yaml --trust-policy trust.yaml

Common Patterns¶

Pattern 1: CI Gate¶

assay run --config eval.yaml --trace-file traces.jsonl --baseline baseline.json
# Exit 0 = merge allowed
# Exit 1 = block PR

Pattern 2: Learning Mode¶

assay policy record --output policy.yaml -- your-agent-command
assay policy generate -i traces/session.jsonl --output policy.yaml

Pattern 3: Debug Violation¶

assay doctor                           # Check setup
assay explain --trace traces.jsonl --policy policy.yaml  # Explain failure
assay coverage --trace-file traces.jsonl # Check coverage

Pattern 4: Baseline Regression¶

# On main branch
assay run --config eval.yaml --export-baseline baseline.json

# On feature branch
assay run --config eval.yaml --baseline baseline.json

Crate Responsibilities¶

Key Paths in Codebase¶

crates/assay-cli/src/cli/commands/mod.rs  # Command dispatch
crates/assay-core/src/engine/runner.rs    # Test execution
crates/assay-core/src/storage/store.rs    # SQLite persistence
crates/assay-core/src/mcp/proxy.rs        # MCP proxy
crates/assay-core/src/report/sarif.rs     # SARIF output
crates/assay-cli/src/templates.rs         # CI templates
infra/bpf-runner/health_check.sh          # Runner health
.github/workflows/kernel-matrix.yml       # eBPF CI

Environment Variables¶

Related Documentation¶

• Run Output - run.json / summary.json contract (seeds, judge_metrics)
• Decision Trees - When to use which approach
• Entry Points - Full command reference
• Codebase Overview - Architecture details