SHADI

Secure Host for Agentic AI Dynamic Instantiation (SHADI) is a secure host runtime for autonomous, multi-agent systems.

SHADI is designed for environments where agents are long-lived, hold real credentials, and run close to sensitive data. It combines identity verification, keychain-backed secrets, OS sandboxing, and encrypted local memory to reduce blast radius and make agent behavior auditable.

What SHADI provides

• Verified secret access gates (agent_secrets) with OS keychain backends.
• Deterministic human -> agent identity derivation (did:key) and provenance verification.
• Kernel-enforced sandbox execution policies (shadi_sandbox) with portable profile defaults.
• Process-scoped secret delivery policy with exact executable matching, explicit disclosure paths, and trusted child-delivery on Unix/macOS.
• Opt-in Git-backed sandbox snapshots for before/after working-tree capture and audit trails.
• SQLCipher-backed encrypted local memory (shadi_memory).
• Python bindings (shadi_py) for secrets, memory, and sandboxed execution.
• SLIM transport integration for secure agent-to-agent messaging.
• Example agents and demos, including a practical SecOps workflow and launch scripts.

Recent updates in this branch of the project:

• SecOps now treats container CVEs as rebuild or base-image refresh work instead of mutating Dockerfiles with ad-hoc package upgrade lines.
• Dockerfile resolution for container findings is workflow-first, using .github/workflows/* metadata before repo-wide scanning.
• Demo launchers are hardened for the optional 1Password backend by reading required secrets before entering the sandbox.
• Avatar surfaces clearer SLIM handshake errors when the SecOps A2A side is unavailable or misconfigured.

Repository layout

• crates/shadictl: main CLI (shadi) for policy, sandbox execution, key management, and identity derivation/verification.
• crates/shadi_sandbox: sandbox policy model and platform enforcement.
• crates/agent_secrets: keychain-backed secret storage + verification-gated access.
• crates/shadi_memory: SQLCipher memory library (accessed via shadictl memory).
• crates/shadi_py: Python extension module shadi.
• crates/agent_transport_slim + crates/slim_mas: secure transport and moderation helpers (with shadictl slim-mas).
• agents/secops: example SecOps workload, A2A server, and skill implementation.
• docs: architecture, security, CLI, demos, and integration docs.
• scripts: local launch helpers for SLIM + agent demos.

Architecture at a glance

SHADI runtime flow:

1. Ingest human identity material (gpg secret material or generic seed).
2. Derive deterministic Ed25519 local keys and did:key identities per agent.
3. Optionally bind agent identities to a stored human DID and verify provenance.
4. Resolve sandbox and secret-delivery policy for the exact launched executable.
5. Gate secret access on verified sessions and deliver secrets through the allowed disclosure or trusted-delivery path.
6. Persist agent memory encrypted at rest.

Current secret-delivery modes:

• --inject-keychain and process_inject_keychain: explicit env disclosure to the launched process.
• process_trusted_secret: process-scoped direct trusted-secret delivery; on Unix/macOS this is a one-shot broker fetch with a nonce-bound endpoint, and on Windows it remains a compatibility handle path.
• process_secret_policy: action-based policy rules. delegate-to-child is implemented for Unix/macOS final-consumer delivery; use is modeled in policy for narrower future mediation patterns.

Platform presentation layers:

1. Experience and control: operators define profiles, policies, and launch intent.
2. Secure runtime: identity, secret control, trusted delivery, sandboxing, transport, and encrypted memory enforce the launch contract.
3. Protected workloads: agents and tools run inside the approved runtime boundary.
4. External systems: GitHub, model providers, and SLIM/A2A peers are reached only after policy and trust checks pass.

For full details, see docs/architecture.md and docs/security.md.

Prerequisites

• Rust toolchain (stable) with Cargo
• Python 3.12 (for shadi_py and Python demos)
• just (recommended task runner)
• Optional for docs: mkdocs (and related theme/plugins used by this repo)

Quick start

Build all crates:

cargo build --workspace

Run all tests:

cargo test --workspace

If you use just, common tasks are available:

just build
just test
just lint

Use just --list or just --groups to browse tasks by area.

Core CLI workflows

1) Print a baseline secure policy profile

cargo run -p shadictl -- --profile balanced --print-policy

Available built-in profiles:

• strict: local-only policy with network blocked
• balanced: practical local default with network blocked
• connected: balanced + network enabled

Inspect effective configuration and policy provenance:

cargo run -p shadictl -- config show --format json
cargo run -p shadictl -- policy explain --format json
cargo run -p shadictl -- policy diff --against profile:strict --format json

With explicit policy file and CLI overrides:

cargo run -p shadictl -- \
	config show \
	--profile connected \
	--policy ./sandbox.json \
	--allow . \
	--allow-command curl \
	--format json

Quickly inspect policy source attribution:

cargo run -q -p shadictl -- policy explain --policy ./sandbox.json --format json | jq '.sources'

2) Run a command in the sandbox

cargo run -p shadictl -- \
	--allow . \
	--read / \
	--net-block \
	-- \
	/usr/bin/env echo "hello from sandbox"

3) Capture a Git-backed sandbox snapshot

Use this when you want a stable artifact describing what a sandboxed command changed inside a Git working tree:

cargo run -p shadictl -- \
	--allow . \
	--git-snapshot \
	--git-snapshot-untracked \
	-- \
	./your-agent

Artifacts are opt-in and written by default to ${SHADI_TMP_DIR:-./.tmp}/git-snapshots, with a stable layout:

• runs/<artifact_id>/snapshot.json: canonical per-run artifact
• latest.json: copy of the most recent snapshot

Each artifact includes resolved policy, timestamps, before/after Git state, SHA-256 hashes for captured Git payloads, and comparison fields such as status_changed and overall_changed.

If the workspace contains nested Git repos, the artifact also includes a git.repositories array with per-repo before/after state and comparison metadata. This is important for agent workflows like SecOps remediation where the agent may clone or update another repo under the current working folder: the outer repo can stay unchanged while the nested repo entry still reports the change.

4) Derive agent identities from a human source

cargo run -p shadictl -- \
	derive-agent-identity \
	--source gpg \
	--human-secret human/gpg \
	--name secops-a \
	--name avatar-1 \
	--prefix agents \
	--out-dir ./agent-dids

5) Verify agent provenance

cargo run -p shadictl -- \
	verify-agent-identity \
	--source gpg \
	--human-secret human/gpg \
	--name secops-a \
	--prefix agents

6) Use encrypted memory through shadictl

cargo run -p shadictl -- memory init \
	--db "${SHADI_TMP_DIR:-./.tmp}/shadi-memory.db" \
	--key-name shadi/memory/sqlcipher_key

Python module (shadi_py)

Build the Python extension crate:

cargo build -p shadi_py

The module exposes bindings for:

• secret store operations and session verification hooks
• SQLCipher memory operations
• sandbox policy handles and sandboxed process execution

SecOps demo and launch scripts

The repo includes runnable demo workloads under agents/secops and helper scripts in scripts/.

Common local flow:

./scripts/launch_slim.sh
./scripts/import_secops_secrets.sh
./scripts/launch_secops_a2a.sh
./scripts/launch_avatar.sh

Focused Python tests for the SecOps skill:

just secops-test-python

Security scan for the SecOps skill package:

just secops-skill-scan

See scripts/README.md and docs/demo.md for full setup details.

Documentation

Primary docs live in docs/:

• docs/index.md: project overview
• docs/architecture.md: runtime and control planes
• docs/security.md: threat model and security notes
• docs/cli.md: complete CLI reference
• docs/sandbox.md: policy model and profile behavior
• docs/demo.md: demo walkthrough
• docs/secops_agent.md: SecOps demo workload and remediation behavior

Build/serve docs locally:

mkdocs build
mkdocs serve

Development notes

• Keep changes focused and platform-safe (macOS, Windows, Linux where applicable).
• Prefer policy/profile-based secure defaults instead of ad-hoc shell wrappers.
• Use deterministic identity derivation and verify-agent-identity for provenance checks.
• Run cargo test --workspace before opening a PR.

Contributing

See:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md

License

See LICENSE.md.