AstraGraph

Policy-enforced observability for tool-using, multi-agent systems.

AstraGraph sits in front of MCP and A2A traffic, evaluates every action against policy, and writes a causal graph plus audit trail you can query in real time.

Why AstraGraph

• Prevent unsafe tool calls before execution with fail-closed enforcement.
• Reconstruct who did what and why as a causal coordination graph.
• Investigate violations fast with searchable audit records and workflow-level traces.
• Support multi-agent workflows where MCP and A2A interactions mix in one run.

System Architecture

%%{init: {'theme':'base','themeVariables':{
'primaryColor':'#e6fffa',
'primaryTextColor':'#102a43',
'primaryBorderColor':'#1f7a8c',
'lineColor':'#1f7a8c',
'secondaryColor':'#f0fff4',
'tertiaryColor':'#fffaf0'
}}}%%
flowchart LR
    AGENTS["Agents (MCP + A2A)"] --> PROXY["AstraGraph Proxy (Rust)"]
    PROXY --> POLICY["Policy Service (Rust)"]
    PROXY --> GRAPH["Graph Service (Rust)"]
    PROXY --> VERIFIER["Verifier Service (gRPC contract; startup behavior configurable)"]
    GRAPH --> DASH["Dashboard (React/Vite)"]
    POLICY --> DASH
    POLICY --> POLICYFILES["Policy YAML Files"]
    GRAPH --> DATASTORE["Graph + Audit Data"]

    classDef edge fill:#e6fffa,stroke:#1f7a8c,stroke-width:2px,color:#102a43;
    classDef core fill:#fffaf0,stroke:#f59e0b,stroke-width:2px,color:#102a43;
    classDef store fill:#f0fff4,stroke:#2f855a,stroke-width:2px,color:#102a43;

    class AGENTS,DASH edge;
    class PROXY,POLICY,GRAPH,VERIFIER core;
    class POLICYFILES,DATASTORE store;

Loading

Request Decision Flow

sequenceDiagram
    participant A as Agent
    participant P as Proxy
    participant S as Policy
    participant V as Verifier
    participant G as Graph

    A->>P: MCP tool call / A2A task
    P->>S: Evaluate(policy_id, action, context)
    alt policy denies
      S-->>P: deny + rule_id
      P->>G: Write blocked action/audit metadata
      P-->>A: 403 POLICY_VIOLATION
    else policy allows
      S-->>P: allow + threshold/fallback
      P->>V: Score deviation (or timeout)
      alt verifier unavailable and fallback=QUEUE
        P->>G: Write queued action/audit metadata
        P-->>A: 403 POLICY_VIOLATION (QUEUE detail)
      else verifier response available
        V-->>P: score, rationale
        P->>G: Write action + verification metadata
        alt missing trace and tool not allowlisted
          P-->>A: 403 POLICY_VIOLATION
        else score within threshold
          P-->>A: Forward to upstream and return result
        else score violates policy
          P-->>A: 403 POLICY_VIOLATION
        end
      end
    end

Loading

Quickstart (10 Minutes)

Prerequisites

• Docker Desktop
• Python 3.11+ (3.12+ recommended)
• make
• Rust toolchain (only needed for local non-container runs)

Run the 3-Agent E2E Gate

From this directory:

./scripts/e2e_run.sh

To run E2E with the real verifier service path instead of the deterministic mock:

./scripts/e2e_run.sh --real-verifier

To include verifier-outage queue fallback coverage in the E2E run:

./scripts/e2e_run.sh --queue-fallback

The script:

1. Generates local TLS certs (make certs)
2. Starts core services + 3 fixture agents via Docker Compose
3. Runs scripts/e2e_three_agent_gate.py --scenario standard
4. Optionally runs --scenario queue-fallback with verifier stopped (--queue-fallback)
5. Tears everything down

Verifier implementation status (important)

• The proxy requires a verifier gRPC dependency by default (ASTRAGRAPH_VERIFIER_REQUIRED_AT_STARTUP=true).
• You can allow degraded startup with ASTRAGRAPH_VERIFIER_REQUIRED_AT_STARTUP=false (proxy starts and enforces fallback behavior when verifier is unavailable).
• Default E2E mode uses scripts/mock_verifier.py for deterministic CI and local testing.
• --real-verifier uses verifier/server.py (reference Python implementation).
• Production deployments should replace the verifier backend with your own service that implements the same gRPC interface documented in verifier/INTERFACE.md.
• If verifier scoring is unavailable and policy fallback is QUEUE, AstraGraph returns a queue-fallback policy violation envelope.

Expected final output:

{"workflow_id":"wf-three-agent-e2e","status":"pass", ...}

What the E2E Gate Proves

The gate validates all core controls in one run:

• A2A task handoff succeeds (/a2a/tasks/send)
• Malformed MCP JSON is rejected by upstream (400 invalid json)
• Safe MCP tool call is allowed (safe_tool)
• Missing-trace MCP call is blocked (review_summary without thinking -> 403 POLICY_VIOLATION)
• Risky tool call is blocked (export_data -> 403 POLICY_VIOLATION)
• Block reason includes policy rule (rule-export-block)
• Graph store contains both allowed + blocked action nodes
• Audit endpoint returns a persisted violation record
• Queue fallback path returns POLICY_VIOLATION envelope with QUEUE detail when verifier is unavailable (--queue-fallback)

Local Development

Start full stack

docker compose up --build

Deployment profiles (explicit defaults)

Use profile env files to make runtime intent explicit:

docker compose --env-file ops/profiles/dev.env up --build
docker compose --env-file ops/profiles/non-dev.env up --build

• ops/profiles/dev.env: local development defaults (ASTRAGRAPH_E2E_VERIFIER_MODE=mock, non-blocking verifier startup).
• ops/profiles/non-dev.env: staging/production-like defaults (ASTRAGRAPH_E2E_VERIFIER_MODE=real, verifier required at startup, fail-closed).

Useful make targets

make certs
make dev-test
make dev-dashboard
make proto-gen
cargo test -p astragraph-policy policy_regression_packs_pass

Policy simulation CLI (what-if decisions)

Single scenario:

cargo run -p astragraph-policy --bin policy_simulator -- \
  --policy policy-bundles/e2e-policy.yaml \
  --agent lead-scorer \
  --tool export_data \
  --args '{"table":"customers"}' \
  --now-utc "10:30 UTC"

Regression pack:

cargo run -p astragraph-policy --bin policy_simulator -- \
  --pack tests/policy_regressions/finance_guardrails.yaml --strict

Enable advanced policy mode in simulation:

cargo run -p astragraph-policy --bin policy_simulator -- \
  --policy policy-bundles/e2e-policy.yaml \
  --agent lead-scorer \
  --tool export_data \
  --advanced-mode

Migrate YAML rules to advanced mode suggestions:

cargo run -p astragraph-policy --bin policy_migrate -- \
  --input policy-bundles/e2e-policy.yaml \
  --engine OPA_COMPAT \
  --output /tmp/e2e-policy-v2.yaml

Dashboard

By default:

• URL: http://localhost:5173
• Graph API base: http://localhost:8080 (override with VITE_GRAPH_API)
• Built-in incident triage workflows:
  • incident timeline (timestamped violation stream)
  • drift-path surfacing (node + drift chain drill-down)
  • policy hit analytics (top rules/agents/workflows)
  • SLO slices (p50/p95/p99 latency, block rate, false-positive review queue)

Core APIs

Graph service (:8080, requires Authorization: Bearer <token>):

• GET /graphs
• GET /graphs/:id
• GET /graphs/:id/nodes
• GET /graphs/:id/drift-path/:node_id
• GET /audit/violations
• GET /audit/violations/:id
• GET /audit/slo (latency/block-rate/review-queue SLO slices)
• GET /audit/export (format=csv|json, optional schema=soc2_v1|iso42001_v1)

Policy service (:8081, requires bearer token):

• GET /policies
• GET /policies/:name
• POST /policies/validate (optional signature field when bundle signing is enabled)
• GET /policies/:name/history
• GET /policies/:name/rollout
• POST /policies/:name/rollout (start/update canary rollout, optional signature)
• POST /policies/:name/rollout/promote (promote candidate to stable)
• POST /policies/:name/rollback (rollback active rollout)

Compatibility reference: docs/api_policy_compatibility_matrix.md Advanced policy mode reference: docs/advanced_policy_mode.md Model upgrade protocol: docs/model_upgrade_protocol.md Enterprise reference architecture: docs/enterprise_reference_architecture.md Kubernetes multi-tenant deployment: docs/kubernetes_multi_tenant_reference.md Adoption playbooks: docs/adoption_playbooks.md Public roadmap: docs/public_roadmap.md Community contribution track: docs/community_contribution_track.md

Proxy HTTP entrypoint (:7070):

• POST /mcp/tools/call
• POST /a2a/tasks/send

Example API Calls

curl -H "Authorization: Bearer dev-token" \
  http://localhost:8080/graphs

curl -H "Authorization: Bearer dev-token" \
  "http://localhost:8080/audit/violations?workflow_id=wf-three-agent-e2e"

curl -X POST -H "Authorization: Bearer dev-token" -H "Content-Type: application/json" \
  "http://localhost:8081/policies/e2e-policy/rollout" \
  -d '{"percentage":20,"yaml":"apiVersion: astragraph.io/v1\nkind: AgentPolicy\nmetadata:\n  name: e2e-policy\n  version: \"1.1\"\n  owner: \"astragraph-dev@local\"\nspec:\n  agents:\n    - name: lead-scorer\n      tier: 3\n      allowed_tools: [safe_tool, review_summary, export_data, a2a.tasks.send]\n      blocked_tools: []\n  rules:\n    - id: rule-export-block\n      description: Block export_data in e2e gate\n      condition: \"action.tool == export_data\"\n      action: BLOCK\n  verification:\n    threshold: 0.7\n    model: \"mock-verifier\"\n    fallback: ALLOW\n","signature":"'"$SIGNATURE"'"}'

curl -X POST -H "Authorization: Bearer dev-token" \
  "http://localhost:8081/policies/e2e-policy/rollback"

Rollout Metrics and Alert Hooks

• Policy service emits rollout telemetry:
  • astragraph.policy.rollout.events.total (labels: policy, event, status)
  • astragraph.policy.rollout.active (active rollout up/down counter by policy)
• Optional webhook hook for rollout lifecycle events:
  • ASTRAGRAPH_POLICY_ALERT_WEBHOOK_URL
  • ASTRAGRAPH_POLICY_ALERT_WEBHOOK_TOKEN (optional bearer token)
• Optional signed policy bundle enforcement:
  • Set ASTRAGRAPH_POLICY_BUNDLE_SIGNING_KEY=<shared-secret> on the policy service.
  • When enabled, POST /policies/validate and POST /policies/:name/rollout require signature (JWT signed with HS256 whose payload contains the exact raw YAML under yaml).
  • Signature example:

export ASTRAGRAPH_POLICY_BUNDLE_SIGNING_KEY='dev-shared-secret'
POLICY_YAML="$(cat policy-bundles/e2e-policy.yaml)"
SIGNATURE="$(
python3 -c "import base64, hashlib, hmac, json, os; y=open('policy-bundles/e2e-policy.yaml').read(); h={'alg':'HS256','typ':'JWT'}; c={'yaml':y}; e=lambda o: base64.urlsafe_b64encode(json.dumps(o,separators=(',',':')).encode()).rstrip(b'='); hp=e(h)+b'.'+e(c); s=base64.urlsafe_b64encode(hmac.new(os.environ['ASTRAGRAPH_POLICY_BUNDLE_SIGNING_KEY'].encode(), hp, hashlib.sha256).digest()).rstrip(b'='); print((hp+b'.'+s).decode())"
)"

• Prometheus alert rule examples: ops/prometheus/astragraph-policy-rollout-alerts.yaml

Evaluation Gates

• eval/agentbench_eval.py: FAR/VDR gate on eval/agentbench.jsonl
• eval/synthetic_attack_eval.py: synthetic malicious/benign gate on tests/synthetic/attack_traces.jsonl
• eval/anonymized_trace_eval.py: anonymized trace gate on tests/anonymized/anonymized_traces.jsonl
• eval/model_upgrade_gate.py: candidate-vs-baseline verifier upgrade gate
• eval/review_feedback_loop.py: reviewer feedback aggregation into tuning actions
• CI enforces all gates against the proxy fixture before merge.

Repository Layout

• proxy/: Rust sidecar proxy and enforcement layer (MCP + A2A interceptors)
• policy/: Rust policy engine crate (cargo workspace member), serving /policies/* APIs
• policy-bundles/: Sample/versioned policy YAML bundles used for quickstart and simulation
• graph/: Rust graph and audit service (REST + gRPC)
• verifier/: Verifier reference implementation + scoring code (verifier/INTERFACE.md defines the production contract)
• dashboard/: React + Vite operator UI
• connectors/: LangGraph, CrewAI, AutoGen adapters + shared ProxyClient + quickstart.py
• ops/: ops artifacts (Prometheus alert rules + runtime profiles)
• scripts/: E2E gate, fixtures, mocks, cert generation
• tests/: integration, synthetic, and anonymized evaluation assets
• data/: Local runtime state (policy history and graph/audit JSONL files for dev/e2e)
• charts/: Helm chart manifests
• docs/schemas/: SOC2 + ISO42001 audit export schemas
• docs/repo_structure.md: contributor-oriented map of naming conventions and top-level directories

Security and Operations Notes

• Default mode is intended to be fail-closed (fail_closed = true in astragraph-proxy.toml).
• In production, keep ASTRAGRAPH_VERIFIER_REQUIRED_AT_STARTUP=true unless you intentionally run degraded startup with strict fallback (QUEUE or BLOCK).
• Local certs in certs/ are for development. Use managed PKI in production.
• Do not expose demo tokens or local auth settings in internet-facing deployments.

Roadmap-Friendly Extensions

• Use ./scripts/e2e_run.sh --real-verifier to exercise the real verifier path in E2E.
• Use ./scripts/e2e_run.sh --queue-fallback to exercise verifier-outage queue fallback coverage.
• Add organization auth provider and stricter role mapping for graph/policy APIs.
• Back graph/audit storage with durable external DB for high-volume workloads.
• Extend policy regression packs in tests/policy_regressions/ and keep them green in CI.

License

Apache-2.0. See LICENSE.

GitAgent Standard Overlay

This repository now includes the AgentStack GitAgent overlay:

• agent.yaml for identity, policy binding, and skill manifest
• SOUL.md for operator-facing identity and mission
• RULES.md for human-readable constraints mapped to runtime policy
• memory/ for auto-committed audit/test history
• skills/ for executable capability descriptors
• hooks/ for pre/post execution governance automation

The overlay is additive: existing APIs and runtime behavior are unchanged unless these new files/hooks are explicitly used.