Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/affaan-m/ECC/llms.txt

Use this file to discover all available pages before exploring further.

Agent security is no longer theoretical. With continuous-run harnesses like Claude Code operating at scale, the attack surface has expanded dramatically: every repo a coding agent reviews, every MCP server it connects to, every PDF it reads, and every hook it executes is a potential entry point. ECC treats security as infrastructure — not an afterthought — and ships with layered defenses designed to shrink the blast radius when something inevitably goes wrong.
Only install ECC from official distribution surfaces: the ecc-universal npm package, the affaan-m/ECC GitHub repository, the ecc-tools GitHub App, or the ecc@ecc marketplace slug. Packages such as @chil_ntl/ecc-cli, ecc-100xprompt-plugin, opencode-ecc, and everything-claude-code are not maintained by ECC. Treat any unlisted package as unofficial until verified.

​
Security philosophy

ECC’s approach is defense-in-depth for agentic workflows. No single control stops every class of attack. Instead, multiple independent layers — hook-based gates, supply-chain scanning, sandbox isolation, permission denylists, and counterparty reputation checks — are combined so that a failure in one layer does not cascade into a full compromise. The guiding principle, drawn directly from ECC’s security guide: never let the convenience layer outrun the isolation layer.

​
Major threat categories

The following threat classes are documented in the ECC security guide and inform every defensive decision in the project.
Prompt injection is the primary entry point for agentic exploitation. A direct injection targets the model’s system prompt or user turn. An indirect injection embeds malicious instructions in content the agent reads autonomously — PR review comments, PDF attachments, web pages, tool output, MCP server responses, or memory files.Once malicious text enters the context window, there is no meaningful runtime distinction between “data” and “instructions.” Simon Willison’s lethal trifecta captures the risk: when private data, untrusted content, and external communication all share the same runtime, prompt injection becomes data exfiltration.Real-world baseline: Snyk’s ToxicSkills study scanned 3,984 public AI agent skills and found prompt injection in 36% of them, with 1,467 malicious payloads identified.
Agents with broad tool permissions can be coerced into reading secrets, executing arbitrary shell commands, making outbound network calls, or writing outside the project workspace. CVE-2025-59536 (CVSS 8.7) demonstrated that project-contained code in Claude Code could execute before the user accepted the trust dialog.ECC ships a recommended baseline denylist:
{
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(**/.env*)",
      "Write(~/.ssh/**)",
      "Write(~/.aws/**)",
      "Bash(curl * | bash)",
      "Bash(ssh *)",
      "Bash(scp *)",
      "Bash(nc *)"
    ]
  }
}
This is a solid baseline — not a complete policy. Scope permissions to the minimum the task actually needs.
The npm and PyPI ecosystems are active attack surfaces. Malicious package versions, dependency confusion, and typosquatting can inject hostile code before an agent session even starts. CVE-2026-21852 showed how an attacker-controlled project could override ANTHROPIC_BASE_URL to redirect API traffic and leak keys.ECC addresses this with AgentShield: automated IOC scanning across npm/PyPI dependency trees, installed package payloads, and AI-tool persistence paths. See AgentShield for full details.
Agents running without isolation can access the host filesystem, environment variables, long-lived credentials, and network interfaces beyond their task scope. If an agent is compromised, the blast radius must be contained.Recommended isolation pattern using Docker Compose:
services:
  agent:
    build: .
    user: "1000:1000"
    working_dir: /workspace
    volumes:
      - ./workspace:/workspace:rw
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    networks:
      - agent-internal

networks:
  agent-internal:
    internal: true
internal: true means a compromised agent cannot phone home unless you deliberately give it a route out.
Persistent memory is a high-value target. Microsoft’s February 2026 AI Recommendation Poisoning report documented memory-oriented attacks across 31 companies and 14 industries. The payload does not need to win in one shot — it can plant fragments across sessions and assemble later.ECC’s guidance: keep memory narrow and scoped to the project, never store secrets in memory files, reset memory after untrusted runs, and disable long-lived shared memory for high-risk workflows.
Hidden Unicode characters (zero-width spaces, bidirectional override characters), HTML comments, and embedded base64 can carry instructions that humans miss but models execute. MCP tool descriptions and schemas are also in-context and can lie.Quick scan for hidden characters:
# Zero-width and bidi control characters
rg -nP '[\x{200B}\x{200C}\x{200D}\x{2060}\x{FEFF}\x{202A}-\x{202E}]'

# HTML comments, script tags, or suspicious data URIs
rg -n '<!--|<script|data:text/html|base64,'
OWASP’s MCP Top 10 now explicitly lists tool poisoning, prompt injection via contextual payloads, and shadow MCP servers as documented attack categories.

​
ECC’s built-in defenses

AgentShield IOC Scanning

Automated supply-chain scanning for npm/PyPI dependencies, AI-tool persistence paths (MCP configs, hook scripts, Claude settings), and config files. Runs via npx ecc security-ioc-scan or in CI. See the full AgentShield page.

AURA Trust Check

Opt-in, read-only counterparty reputation check via a zero-dependency Python adapter. Blocks high_risk and unknown counterparties before settlement or delegation actions. See the full AURA Trust page.

PreToolUse Hook Gates

Hook-based security gates that sit between the model and the action. The model is never the final authority for shell execution, network egress, secret reads, or off-repo writes. Hook configuration lives in .claude/settings.json.

Workflow Security Validation in CI

GitHub Actions workflows in the ECC repo use pinned commit SHAs for all third-party actions and avoid shelling untrusted GitHub context directly into run: blocks. Supply-chain IOC scanning runs in CI before release.

Secrets Guidance via .env.example

mcp-configs/mcp-servers.json ships as a template with all YOUR_*_HERE placeholders. ECC’s security policy requires that real credentials are resolved at spawn time from the OS keychain or environment variables — never committed to the repository.

Process-group Kill & Heartbeat

Kill the process group, not just the parent, to prevent orphaned child processes from continuing after a forced stop. Unattended loops should implement a heartbeat-based dead-man switch: if the agent stops checking in, the supervisor kills the process group automatically.
Install ECC with the security profile to enable AgentShield scanning and hook-based gates in a single step: 
npx ecc-universal install --profile security
Or enable the security module on an existing installation: 
npx ecc-universal install --modules security
The --profile security preset configures:
  • Supply-chain IOC scanning via AgentShield
  • Hook-based PreToolUse security gates
  • The recommended permissions denylist
  • AURA trust-check adapter (opt-in, requires explicit call)

​
Minimum bar checklist

If you are running ECC agents autonomously, the following is the minimum security baseline:
1

Separate agent identities

Create dedicated agent accounts (agent@yourdomain.com, separate GitHub bot token, separate Slack bot). A compromised agent with your personal credentials is you.
2

Use short-lived scoped credentials

Rotate tokens. Never commit API keys. Resolve secrets from the OS keychain or environment variables at spawn time.
3

Run untrusted work in isolation

Use Docker containers, devcontainers, VMs, or remote sandboxes for repos and attachment-heavy workflows. Set internal: true on agent networks to deny outbound traffic by default.
4

Restrict tools and paths

Apply the permissions denylist. If a workflow only reads a repo and runs tests, do not let it read your home directory or touch production.
5

Sanitize foreign content

Strip hidden Unicode, HTML comments, and metadata from PDFs, screenshots, and HTML before a privileged agent reads them. Keep the extraction step separate from the action-taking agent.
6

Require approval at trust boundaries

Unsandboxed shell commands, network egress, secret reads, off-repo writes, and workflow dispatch all require human or policy approval — not just the model’s judgment.
7

Log tool calls and approvals

Structured logs covering tool name, input summary, files touched, approval decisions, and network attempts are the minimum. Wire into OpenTelemetry for scale.
8

Scan your supply chain

Run npx ecc security-ioc-scan before deploying to any production agent environment. Treat skills, hooks, MCP configs, and agent descriptors as supply chain artifacts.

​
Reporting a vulnerability

Report vulnerabilities via GitHub private vulnerability reporting or email affaan@ecc.tools. Do not open a public GitHub issue. The security@ecc.tools alias is not monitored — use affaan@ecc.tools. See SECURITY.md for full scope, supported versions, and expected response timelines (acknowledgment within 48 hours, initial assessment within 7 days).

​
The three security pages

Overview

This page. Threat categories, built-in defenses, and the recommended security baseline.

AgentShield

Supply-chain IOC scanning for npm/PyPI dependencies, AI-tool persistence surfaces, and config files.

AURA Trust

Read-only counterparty reputation checks via a zero-dependency Python adapter.

Build docs developers (and LLMs) love

Get started for freeTalk to us