Security Features

AKIOS protects your AI workflows with multiple layers of defense. This guide explains what security you get and how to verify it's working.

What AKIOS Protects Against

Data Leaks → Automatic PII redaction before data reaches AI providers
Cost Overruns → Hard budget limits with automatic termination
Resource Abuse → CPU, memory, and disk quotas
Unauthorized Access → Sandbox isolation and path restrictions
Audit Gaps → Complete tamper-evident logging of all actions

Security By Platform

Both are production-ready. Use native Linux for absolute maximum, Docker for excellent security everywhere.

The Four Security Layers

0. Security Cage

The Security Cage is the core abstraction — a controlled environment where AI workflows execute with full protections active.

Activate the cage:

# Activate full security: PII redaction, network lock, sandbox, audit
akios cage up

# Check current security posture
akios cage status

# Run diagnostics
akios doctor

When the cage is ACTIVE, these protections are enforced:

• PII Redaction — All inputs/outputs automatically scanned and redacted
• Network Lock — Only LLM API endpoints + configured allowed_domains pass through
• Sandbox — Process isolation via cgroups v2 + seccomp-bpf (native) or container policy (Docker)
• Audit Logging — Every action cryptographically logged with Merkle chains
• Cost Controls — Budget kill-switches halt execution if limits exceeded

Deactivate the cage:

# Cage down — destroy session data (audit/ and data/output/)
akios cage down

# Full erasure including input data
akios cage down --wipe-all

# Multi-pass secure erasure (DOD 5220.22-M)
akios cage down --passes 3

# Fast teardown (truncate-only, dev/CI)
akios cage down --fast

# Dev mode — relax protections but keep data for debugging
akios cage down --keep-data

Note (v1.0.14+): cage down now preserves data/input/ by default — only audit/ and data/output/ are destroyed. Use --wipe-all for full erasure including input data. Use --keep-data to preserve everything during development.

Ablation flags: Benchmark the overhead of individual cage components by selectively disabling them:

akios cage up --no-pii      # Disable PII redaction only
akios cage up --no-audit    # Disable audit only
akios cage up --no-budget   # Disable budget enforcement only

These flags are for benchmarking and testing only — never use them in production.

1. Sandbox & Isolation

What it does: Keeps AI agents in a controlled environment

• Process isolation - Agents can't access the host system
• Syscall filtering - Dangerous system calls are blocked (Linux)
• Resource limits - CPU/memory quotas prevent exhaustion
• Path restrictions - Only allowed directories accessible
• Network control - Default deny, explicit allow only

Verify it's working:

akios status --security
# Look for: Security Level: Full (Linux) or Strong (Docker)

2. PII Redaction

What it does: Automatically removes sensitive data

Protected data types (53 patterns across 6 categories):

• Email addresses, phone numbers
• Social Security numbers, credit cards
• API keys, passwords, tokens
• IP addresses, MAC addresses
• Medical records, health data (NPI, DEA, MRN)
• Financial account numbers
• Insurance data (policy numbers, group numbers, claim numbers, prior-authorization numbers)

Applied twice:

• Before sending to AI providers (inputs)
• After receiving from AI providers (outputs)

Pluggable PII backend: AKIOS uses a PIIDetectorProtocol interface, allowing custom PII detection implementations. The default regex-based detector covers 53 patterns with >95% accuracy.

Context keywords: Reduce false-positive PII matches by requiring contextual keywords near a pattern match. Configure context_keywords in your policy to require words like "SSN", "social security", or "tax ID" near a numeric pattern before flagging it.

Verify it's working:

akios status --security
# Look for: PII Protection: Active (inputs + outputs)

PII marker format: Detected PII is replaced with typed markers using guillemet notation:

Scan files before processing:

akios protect scan data/input/document.txt
akios protect preview templates/workflow.yml

PII fail-safe: If the PII scanner itself encounters an error during processing, the entire input/output is blocked rather than passed through unredacted. This fail-closed behavior ensures sensitive data never leaks due to scanner failures.

# Inspect PII prompt template
akios protect show-prompt

3. Cost Kill-Switches

What it does: Prevents surprise AI bills

• Default budget: $1.00 per workflow
• Token limits: 1000 tokens per API call (default)
• Automatic termination: Workflow stops if budget exceeded
• Loop detection: Catches infinite loops before costs spiral

Verify it's working:

akios status
# Look for: Budget: $0.12 / $1.00 remaining

4. Audit Trail

What it does: Creates tamper-evident logs

• Cryptographic integrity - Merkle-style hash chains
• Complete coverage - Every action logged
• PII-safe - Sensitive data redacted in logs
• Compliance ready - Export for SOX/HIPAA/GDPR

Verify it's working:

akios logs --limit 5
# You should see recent actions with timestamps

Audit management:

# Rotate audit log — archive current chain, start fresh
akios audit rotate

# View aggregate audit statistics
akios audit stats

HTTPS Enforcement

All external API calls made by AKIOS are restricted to HTTPS. Plain HTTP requests are rejected at the transport layer. This applies to:

• LLM provider calls (OpenAI, Anthropic, Grok, Mistral, Gemini)
• HTTP agent requests to allowed_domains
• Any external call made within the security cage

There is no option to downgrade to HTTP. This is a structural guarantee, not a configuration choice.

Check Your Security Status

Quick check:

akios status

Shows: Security level, PII protection, budget remaining, audit status

Detailed security dashboard:

akios status --security

Shows: All security features, active protections, compliance indicators, resource limits

Machine-readable (for scripts):

akios status --security --json

What to Expect

On Native Linux

🛡️ Security Level: Full (kernel-hard)
✓ Sandbox: cgroups v2 + seccomp-bpf active
✓ PII Redaction: Active (inputs + outputs)
✓ Audit Logging: Cryptographic integrity verified
✓ Network: Denied (unless explicitly enabled)
✓ Cost Controls: $1.00 budget limit active

Requirements: Linux kernel 5.4+, system packages libseccomp-dev and python3-seccomp, sudo privileges for full kernel-hard protection. Without sudo, AKIOS gracefully degrades to policy-based mode.

On Docker (any platform)

🛡️ Security Level: Strong (policy-based)
✓ Sandbox: Container isolation active
✓ PII Redaction: Active (inputs + outputs)
✓ Audit Logging: Cryptographic integrity verified
✓ Network: Denied (unless explicitly enabled)
✓ Cost Controls: $1.00 budget limit active

Security Best Practices

√ Do:

• Run akios status --security regularly
• Keep AKIOS updated to latest version
• Review audit logs periodically
• Set appropriate budget limits
• Use environment variables for API keys
• Run in isolated environments for sensitive work

× Don't:

• Commit .env files to version control
• Disable PII redaction in production
• Run with unlimited budgets
• Ignore security warnings
• Share API keys in logs or outputs

Deployable Output

Every workflow execution produces a structured output.json artifact:

akios output latest

The output includes: metadata (version, workflow name, ID, timestamp), execution details (status, steps, timing), security state (PII redaction, audit, sandbox), cost breakdown (total, budget, remaining, over-budget flag), and per-step results with agent, action, status, timing, and output text. Designed for CI/CD pipeline integration.

Data Lifecycle

The cage enforces a strict data lifecycle:

cage up → protections activate → workflows execute → data generated
                                                           ↓
cage down → audit/ destroyed → data/output/ destroyed → data/input/ PRESERVED
                                                           ↓
cage down --wipe-all → data/input/ also destroyed → ZERO DATA RESIDUE

Since v1.0.14, input data is preserved by default on cage teardown. Use --wipe-all for full erasure when zero data residue is required.

Network Security & HTTPS Whitelist

By default, all external network access is blocked (secure-first design). LLM API endpoints (OpenAI, Anthropic, Grok, Mistral, Gemini) always pass through regardless of this setting — the network_access_allowed controls only the HTTP agent.

Configure an HTTPS whitelist for the HTTP agent:

# config.yaml
network_access_allowed: true
allowed_domains:
  - "api.salesforce.com"
  - "api.mycompany.com"

Or via environment variable:

AKIOS_ALLOWED_DOMAINS="api.salesforce.com,api.mycompany.com"

Subdomains must be added explicitly — they are not automatically allowed.

Compliance Frameworks

AKIOS audit exports are designed for regulatory examination across sectors:

Weighted compliance scoring: AKIOS computes a compliance readiness score based on which security components are active. Weights: security 50%, audit 30%, cost 20%. Each component is weighted by its contribution to a given regulatory framework. Run akios status --security to see your current compliance score.

Non-Root Docker Containers

As of v1.0.10, the official AKIOS Docker image runs as a non-root akios user by default. Containers no longer run as root, reducing the blast radius of any container escape vulnerability.

# Official image — already non-root
docker run --rm akiosai/akios:v1.0.15 status

# Verify
docker run --rm akiosai/akios:v1.0.15 id
# uid=1000(akios) gid=1000(akios)

Safe Condition Evaluator

Workflow condition fields are evaluated using an AST-based safe evaluator (v1.0.10). This replaces the previous eval() + token blocklist approach, eliminating code injection risk entirely.

The evaluator supports:

• Comparison operators: ==, !=, >, <, >=, <=
• Boolean operators: and, or, not
• String operations: in, not in
• Variable references: previous_output, step outputs

Arbitrary Python code is not executed — only safe expressions are evaluated.

TLA+ Formal Verification

AKIOS includes a 130-line TLA+ specification that formally verifies the safety invariants of the enforcement pipeline. The specification has been model-checked to prove:

• No PII leakage — data is always redacted before leaving the cage
• Budget enforcement — workflows are always terminated when budget is exceeded
• Audit completeness — every action is logged before execution proceeds
• Sandbox integrity — isolation constraints are never weakened during execution

See docs/tla/AKIOSEnforcement.tla in the repository.

Report Security Issues

Found a vulnerability? Email security@akioud.ai (private only — do NOT report via public GitHub issues)

Include:

• Clear description of the issue
• Steps to reproduce
• Affected versions
• Potential impact (sandbox bypass, PII leak, cost overrun)
• Your contact info

Our response:

• Acknowledgment within 24 hours
• Triage within 72 hours
• Critical fixes within 7 days
• High-severity fixes within 30 days
• Coordinated disclosure
• Public credit (Hall of Fame)

Supported Versions

Always use the latest 1.0.x version for best security.

Learn More

• Concepts - Understand how security layers work
• Configuration - Customize security settings
• Best Practices - Patterns for secure workflows
• Deployment Guide - Security-hardened deployment patterns
• EC2 Deployment Guide - AWS cloud deployment with security best practices
• Debugging - Troubleshoot security issues

Remember: No software is 100% secure. Always validate outputs and run AKIOS in appropriate environments for your security needs.