Security

What aidokit defends against, what it doesn't, and the mitigations the architecture enforces.

What aidokit is and is not

• aidokit is a scaffolding CLI that emits files and runs declared shell commands.
• aidokit is not an LLM client. Zero API calls. No telemetry. No phone-home. No background activity.

Running aidokit is closer to running cookiecutter or npm init than to running an AI service in the cloud.

Trust boundaries

Concentric rings of trust, from your machine outward. Lower trust → stricter gate before any action.

Figure 1. Trust boundaries enforced by the CLI. --yes never bypasses the yellow or red gates.

Mitigations

Capability declarations

Every adapter manifest declares:

capabilityDeclarations:
  writesPaths:    ['CLAUDE.md', '.claude/**', '.aido/**']
  runsShellCommands: ['chmod', 'claude mcp add', 'bd init']
  networkCalls:   []

The conformance harness cross-checks declarations against actual source-level imports (child_process) and call sites (fetch(, http(s).request(). A package that writes outside its declared paths is a conformance violation, not a feature.

Signed packages (v1.0+)

npm audit signatures

Every @aidokit/* package publishes with npm provenance attestations. Verify any installed release with the command above.

Dry-run mode

aidokit init --dry-run and aidokit sync --dry-run print the file plan without writing anything and without running postInstall commands.

Staged writes

Files are written to .aido-staging/ first, then atomically moved into place. A failure during staging leaves your project unchanged and preserves the staging dir for inspection.

Audit log

.aido/state.json records every MCP install with userConfirmed and source: 'catalog' | 'custom'. The log is local; aidokit never transmits it.

Security-sensitive flag is non-bypassable

--yes does not skip confirmation for:

• MCPs marked securitySensitive: true (Filesystem, graphify, …).
• Custom MCPs via --custom-url.
• Tracked-file deletions.
• Package version bumps.

No auto-install of prerequisites

aidokit detects prereqs and prints the per-OS install command. It never invokes brew, apt, scoop, winget, or curl | bash on your behalf. The escape hatch is --skip-prereq-check.

No telemetry

Zero network calls from aidokit itself. The only network calls during normal use come from npm install and from shell commands declared in adapter manifests (e.g. claude mcp add).

What aidokit does not defend against

• An attacker with existing shell access running aidokit as you.
• Compromise of your AI coding CLI (Claude Code, Codex, …).
• Vulnerabilities in MCP server implementations.
• Compromise of npm registry infrastructure (mitigated by provenance verification).
• Network MITM attacks (TLS is assumed to work).
• OS-level privilege escalation.

Reporting a vulnerability

Send vulnerability reports to george@aicenter.ae. Do NOT open public GitHub issues for unpatched vulnerabilities.

Include:

• Affected component (CLI core / specific adapter / stack pack / catalog entry).
• Affected versions.
• Reproducer (steps, sample project).
• What an attacker could accomplish.
• Suggested severity.

Coordinated disclosure timeline

What you can expect: initial acknowledgement within 24h, severity assessment within 72h, coordinated disclosure per the table above.

For adapter / stack-pack / MCP authors

• Declare every glob in writesPaths you actually write to.
• Declare every shell command prefix in runsShellCommands you execute.
• Pass the conformance harness in CI on every published version.
• Sign packages with npm provenance from v1.0 onward.
• Be honest about gaps — document them in manifest.gaps rather than papering over them.