Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
334
AirPlan/docs/architecture/security-model-v1.md
Normal file
334
AirPlan/docs/architecture/security-model-v1.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# AirCoding Security Model V1
|
||||
|
||||
Date: 2026-05-27
|
||||
Status: Canonical security model for V1.0.0 Alpha skeleton
|
||||
|
||||
This document defines AirCoding's MVP security boundaries for local coding-agent operation.
|
||||
|
||||
## 1. Security Goals
|
||||
|
||||
AirCoding should:
|
||||
|
||||
1. Protect user code, credentials, system-sensitive files, and git history.
|
||||
2. Allow productive local development, including C++ build directories and `sudo` when appropriate.
|
||||
3. Make risky actions visible and confirmable.
|
||||
4. Keep local evidence useful for debugging without automatic upload.
|
||||
5. Prevent tool/provider/plugin boundaries from bypassing permissions.
|
||||
6. Preserve recoverability through backups, artifacts, and event history.
|
||||
|
||||
## 2. Trust Boundaries
|
||||
|
||||
```text
|
||||
User
|
||||
→ Main Agent/UI
|
||||
→ Runtime services
|
||||
→ ToolRegistry/PermissionEngine
|
||||
→ OS/filesystem/shell/network/provider
|
||||
```
|
||||
|
||||
Boundary rules:
|
||||
|
||||
1. User instructions are intent, not permission bypass.
|
||||
2. LLM output is untrusted until validated by runtime/tool schemas and PermissionEngine.
|
||||
3. Tool inputs are validated before execution.
|
||||
4. Provider responses cannot directly modify files or run commands.
|
||||
5. Plugins/capabilities use the same ToolRegistry and PermissionEngine path as built-ins.
|
||||
6. Session DB/artifacts are local state, not remote telemetry.
|
||||
|
||||
## 3. Permission Profiles
|
||||
|
||||
```ts
|
||||
type PermissionProfile =
|
||||
| "low"
|
||||
| "normal"
|
||||
| "high"
|
||||
| "developer"
|
||||
```
|
||||
|
||||
Profile behavior:
|
||||
|
||||
| Profile | Behavior |
|
||||
|---|---|
|
||||
| `low` | ask for writes/exec/network beyond read-only inspection |
|
||||
| `normal` | allow project-local work; ask for project-outside/system-sensitive/credentials |
|
||||
| `high` | announce-then-run many allowlisted actions; still ask for credentials/system-sensitive/migrations/destructive shared actions |
|
||||
| `developer` | for AirCoding developers; may emit full encrypted diagnostics; still cannot bypass credential/policy rules |
|
||||
|
||||
## 4. Path Security
|
||||
|
||||
Path categories:
|
||||
|
||||
```ts
|
||||
type PathRiskCategory =
|
||||
| "project"
|
||||
| "project_air_shared"
|
||||
| "project_air_local"
|
||||
| "project_build"
|
||||
| "project_git"
|
||||
| "project_outside_user"
|
||||
| "system_sensitive"
|
||||
| "credential_store"
|
||||
| "unknown"
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. Resolve symlinks with realpath before deciding risk.
|
||||
2. Project directory reads are allowed by default.
|
||||
3. Project directory writes are allowed by default except protected paths.
|
||||
4. `.git/` is write-protected by default.
|
||||
5. Build directories are unrestricted project paths because C++ workflows need them.
|
||||
6. Project-outside non-system writes require backup then allow/ask depending profile.
|
||||
7. System-sensitive and credential-store paths require explicit confirmation or are blocked.
|
||||
8. Unknown paths are treated conservatively.
|
||||
|
||||
System-sensitive examples:
|
||||
|
||||
```text
|
||||
/etc
|
||||
/usr
|
||||
/bin
|
||||
/sbin
|
||||
/boot
|
||||
/dev
|
||||
/proc
|
||||
/sys
|
||||
system service directories
|
||||
package manager global state
|
||||
```
|
||||
|
||||
Credential-store examples:
|
||||
|
||||
```text
|
||||
~/.ssh
|
||||
~/.gnupg
|
||||
password manager stores
|
||||
cloud credential directories
|
||||
.env files when classified as secret-bearing
|
||||
API key config files
|
||||
```
|
||||
|
||||
## 5. Command Security
|
||||
|
||||
Command risk categories:
|
||||
|
||||
```ts
|
||||
type CommandRisk =
|
||||
| "read_only"
|
||||
| "project_write"
|
||||
| "build_or_test"
|
||||
| "network"
|
||||
| "dependency_install"
|
||||
| "destructive"
|
||||
| "system_sensitive"
|
||||
| "credential_access"
|
||||
| "privilege_escalation"
|
||||
| "unknown"
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `sudo` alone is not automatically forbidden.
|
||||
2. `sudo` touching system-sensitive paths still requires explicit confirmation.
|
||||
3. Destructive commands are never run silently unless narrowly allowlisted and recoverable.
|
||||
4. Interactive commands are not supported in MVP except through dedicated tools.
|
||||
5. Commands must have cwd and timeout.
|
||||
6. stdout/stderr are captured as artifacts when needed for evidence.
|
||||
7. Shell execution is non-interactive and does not inherit secrets except allowlisted environment variables.
|
||||
|
||||
Destructive examples:
|
||||
|
||||
```text
|
||||
rm -rf
|
||||
reset --hard
|
||||
clean -fd
|
||||
force push
|
||||
dropping databases
|
||||
overwriting user files outside scoped paths
|
||||
killing unrelated processes
|
||||
```
|
||||
|
||||
## 6. Network Security
|
||||
|
||||
Network categories:
|
||||
|
||||
```text
|
||||
provider API calls
|
||||
dependency downloads
|
||||
project-requested network behavior
|
||||
analysis/debug network capture
|
||||
unknown outbound network
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. Provider API calls use configured providers only.
|
||||
2. Dependency downloads are managed through Doctor/setup and permission policy.
|
||||
3. Generated/project code network access must match user request or be approved.
|
||||
4. Network capture may require elevated permissions and explicit reason.
|
||||
5. No automatic upload of doctor bundles, debug knowledge, artifacts, screenshots, logs, pcaps, or source code.
|
||||
|
||||
## 7. Credential Handling
|
||||
|
||||
Credential rules:
|
||||
|
||||
1. Secrets are referenced by `auth_ref`, never copied into session DB/events/artifacts.
|
||||
2. Tools must declare whether input/output may contain secrets.
|
||||
3. Provider adapters redact auth headers and API keys from logs.
|
||||
4. Doctor checks existence/shape of credentials without printing values.
|
||||
5. Credential access always requires explicit confirmation unless already granted by a scoped secure config reference.
|
||||
6. LLM-visible context must not include secrets unless the user explicitly requests and the policy allows it.
|
||||
|
||||
## 8. Provider and Prompt Injection Security
|
||||
|
||||
External content includes:
|
||||
|
||||
```text
|
||||
web pages
|
||||
dependency logs
|
||||
compiler output
|
||||
repo files
|
||||
tool output
|
||||
provider responses
|
||||
MCP/plugin output
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. External content is data, not instruction.
|
||||
2. Tool results cannot override runtime policy or project rules.
|
||||
3. Prompt injection suspicion is surfaced to the user/developer log when relevant.
|
||||
4. ContextAssembler separates instruction layers from evidence/tool output layers.
|
||||
5. Provider output must pass tool schema validation before tool execution.
|
||||
|
||||
## 9. Plugin and Capability Security
|
||||
|
||||
Capabilities declare:
|
||||
|
||||
```text
|
||||
tools provided
|
||||
dependencies
|
||||
permissions requested
|
||||
network access
|
||||
artifact types
|
||||
config schema
|
||||
trust level
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. Capability install/enable is a permissioned action.
|
||||
2. Capability tools are not privileged above built-ins.
|
||||
3. Capability dependencies are detected/installed by Doctor, not by arbitrary plugin scripts.
|
||||
4. Unknown plugin events cannot be durable unless registered or namespaced and approved.
|
||||
5. Capability updates require the same package/source trust policy as install.
|
||||
|
||||
## 10. Logs, Artifacts, and Export
|
||||
|
||||
Local logs:
|
||||
|
||||
```text
|
||||
~/.air/logs/air.log
|
||||
~/.air/logs/air.developer.log
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `air.log` is user-readable and contains startup failures, exceptions, and environment configuration issues.
|
||||
2. `air.developer.log` is full debug/performance log encrypted with development-team public key.
|
||||
3. Logs retain seven days by default.
|
||||
4. Session artifacts are project-local and not automatically redacted.
|
||||
5. Export/share/upload requires explicit user action.
|
||||
6. Debug Knowledge sharing requires redaction, preview, and authorization.
|
||||
7. Doctor bundles may include full diagnostics and are encrypted for development-team channel.
|
||||
|
||||
## 11. Backup and Recovery
|
||||
|
||||
Project-outside writes:
|
||||
|
||||
```text
|
||||
backup to <project>/.air/local/backups/ before write
|
||||
```
|
||||
|
||||
Migration:
|
||||
|
||||
```text
|
||||
always ask user
|
||||
backup .air first
|
||||
rollback on failure
|
||||
```
|
||||
|
||||
Workspace merges preserve conflict artifacts and do not discard user work silently.
|
||||
|
||||
## 12. Refusal and Block Conditions
|
||||
|
||||
AirCoding refuses or blocks:
|
||||
|
||||
```text
|
||||
malware, credential theft, stealth, evasion, destructive abuse
|
||||
unauthorized access or exploitation
|
||||
mass targeting or DoS
|
||||
supply-chain compromise
|
||||
unapproved credential access
|
||||
unapproved destructive shared-state actions
|
||||
policy-bypassing requests
|
||||
```
|
||||
|
||||
Defensive security, authorized testing, CTF, and educational work are allowed when authorization context is clear.
|
||||
|
||||
## 13. PermissionEngine API
|
||||
|
||||
```ts
|
||||
interface PermissionRequestContext {
|
||||
session_id: string
|
||||
task_id?: string
|
||||
agent_id?: string
|
||||
tool_name?: string
|
||||
command?: string
|
||||
paths?: string[]
|
||||
network?: boolean
|
||||
requested_action: string
|
||||
reason: string
|
||||
}
|
||||
|
||||
type PermissionAction = "allow" | "deny" | "ask_user" | "block" | "refuse" | "announce_then_run"
|
||||
type PermissionGrantScope = "none" | "once" | "session" | "project" | "global"
|
||||
|
||||
interface PermissionDecision {
|
||||
action: PermissionAction
|
||||
grant_scope: PermissionGrantScope
|
||||
risk_level: "low" | "medium" | "high" | "critical"
|
||||
reason: string
|
||||
required_confirmation?: boolean
|
||||
backup_required?: boolean
|
||||
evidence_refs?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
Permission decisions are recorded with `permission.decision.recorded` when durable.
|
||||
|
||||
## 14. V1.0.0 Alpha Cut Line
|
||||
|
||||
V1.0.0 Alpha skeleton must implement:
|
||||
|
||||
1. Realpath-based path classifier.
|
||||
2. Command risk analyzer.
|
||||
3. Permission profiles.
|
||||
4. Explicit credential/system-sensitive confirmation gates.
|
||||
5. Project-outside backup-before-write path.
|
||||
6. ToolRegistry permission enforcement.
|
||||
7. Provider secret redaction.
|
||||
8. Export/share no-auto-upload rule.
|
||||
9. Security refusal/block handling.
|
||||
10. Permission decision events.
|
||||
|
||||
Post-MVP:
|
||||
|
||||
```text
|
||||
sandboxed command runner
|
||||
seccomp/container profiles
|
||||
plugin signature verification
|
||||
secret scanner integration
|
||||
advanced prompt-injection classifier
|
||||
policy-as-code engine
|
||||
```
|
||||
Reference in New Issue
Block a user