agentsecure 0.1.0

Local-first security runtime for AI coding agents

AgentSecure Community

By ShellFrame AI

AgentSecure Community is the open-source community/lite edition of AgentSecure by ShellFrame AI. It is a local-first demo runtime for AI coding agents that shows how an agent can work in a real project while seeing virtual secrets instead of raw .env values.

This repository is intentionally scoped to local CLI, local command guard, basic policy config, local secret virtualization, and tests. Hosted cloud sync, enterprise policy management, billing/licensing, and sensitive commercial detection logic are not part of this release.

Ownership

AgentSecure and ShellFrame AI are ShellFrame AI project names. This community repository is published to demonstrate the local-first secret virtualization model while keeping commercial/backend features private.

What It Demonstrates

• Discover likely secrets in .env files and environment variables.
• Store real values locally under .agentsecure/.
• Expose virtual values such as OPENAI_API_KEY=virt_openai_....
• Sanitize common .env reads through command-guard mode.
• Remove denied env values from agent-visible output.
• Keep basic network, process, and file policy in JSON.

Command-guard mode is a usability guard, not a hard sandbox. A determined process can bypass wrapper-based masking. Use workspace copy mode or OS sandboxing for stronger isolation.

Install

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Quickstart

Run the safe local demo:

agentsecure demo

Expected output includes a virtual OpenAI key and an explanation that DATABASE_URL_PROD was removed by policy:

Agent-visible output:
OPENAI_API_KEY=virt_openai_...

Try it in a project:

agentsecure init
printf 'OPENAI_API_KEY=sk-demo-local-secret-do-not-use\n' > .env
agentsecure run --protect-all -- python3 -c 'import subprocess; print(subprocess.check_output(["cat", ".env"]).decode())'

The agent-visible output contains a virt_... token. The real .env remains local and unchanged.

Example Policy

See examples/agentsecure.community.json and examples/.env.example.

Minimal policy shape:

{
  "env_policy": {
    "OPENAI_API_KEY": {
      "mode": "virtualize",
      "reason": "Agents see a virtual token, not the local real value."
    },
    "DATABASE_URL_PROD": {
      "mode": "deny",
      "reason": "Production database credentials are never exposed."
    }
  },
  "network": {
    "allow_domains": ["api.openai.com"],
    "allow_ports": [80, 443],
    "deny_ip_literals": true,
    "deny_private_networks": true
  }
}

Common Commands

agentsecure init
agentsecure status
agentsecure doctor
agentsecure discover
agentsecure suggest
agentsecure env
agentsecure keys list
agentsecure network list

Run an agent or command through local command guard:

agentsecure run --protect-all -- codex
agentsecure run --protect-all -- claude
agentsecure run --protect-all -- python3 -c 'import subprocess; print(subprocess.check_output(["cat", ".env"]).decode())'

Use workspace copy mode when you want review-before-apply:

agentsecure run --runtime workspace --workspace-mode copy --protect-all --workspace-keep -- codex
agentsecure diff
agentsecure apply --dry-run
agentsecure apply

Screenshots / GIFs

Planned public demo assets:

• docs/assets/demo-command-guard.gif: agentsecure demo showing a virtual key.
• docs/assets/dotenv-masking.png: before/after .env masking.
• docs/assets/workspace-diff.png: review-before-apply workflow.

Repository Layout

agentsecure/
  cli/                 CLI entry point
  core/                models, config loading, policy helpers
  guard/               local command guard and output sanitizer
  discovery/           local secret discovery
  implementations/     local secret, grant, policy, and audit storage
  workspace/           safe workspace materialization and apply flow
examples/              community-safe config and fake .env examples
scripts/               release and safety scripts
tests/                 unit and local integration tests

Testing

source .venv/bin/activate
python3 -m unittest discover -s tests -p 'test_*.py' -v
python3 scripts/secret_scan.py .

CI runs tests across supported Python versions and runs the local secret scan.

Public Release Boundary

This community release should not include hosted backend integration, enterprise policy sync, billing/licensing, production secrets, internal endpoints, or sensitive commercial heuristics. See OPEN_SOURCE_PLAN.md before publishing a public GitHub repository.

License

Apache License 2.0 is suggested for the community release. See LICENSE.