Security Documentation¶

Home > Security

Ahoy! This be where ye learn to keep yer ship secure from digital pirates.

Quick Navigation¶

Essential Security Practices:

• Security Recommendations - START HERE for security basics
• Security Context Preservation - Maintain security through sessions

New in PR #1925 (Issue #1922):

• Token Sanitization Guide - Prevent token exposure in logs
• Security API Reference - Complete API documentation
• Security Testing Guide - How to test security features

Security Features Overview¶

Token Sanitization (NEW)¶

Automatically detect and redact sensitive tokens from logs, errors, and debug output.

Quick Start:

from amplihack.proxy.security import TokenSanitizer

sanitizer = TokenSanitizer()
safe_msg = sanitizer.sanitize("Token: gho_abc123xyz")
# Output: "Token: [REDACTED-GITHUB-TOKEN]"

Supported Token Types: - GitHub tokens (gho_, ghp_, ghs_, ghu_, ghr_) - OpenAI API keys (sk-, sk-proj-) - Anthropic API keys (sk-ant-) - Bearer tokens - JWT tokens - Azure keys and connection strings

Documentation: - Token Sanitization Guide - Usage examples and patterns - Security API Reference - Complete API documentation

Model Validation (NEW)¶

Unified model validation preventing routing conflicts and injection attacks.

Features: - Type checking and validation - Format verification (alphanumeric + hyphens/dots) - Path traversal prevention - Length limits (200 chars max) - ASCII-only enforcement

Implementation: ModelValidator class in src/amplihack/proxy/server.py

Input Validation (NEW)¶

Security-focused input validation for all external data.

Features: - Model name validation (prevents injection) - Length checks (reasonable limits) - Character pattern validation - Path traversal checks - Newline/null byte detection

Implementation: validate_model_name() in src/amplihack/proxy/github_models.py

Secure File Permissions (NEW)¶

Automatic secure permissions for sensitive files.

Features: - Token files: 0600 (read/write owner only) - Config directories: 0700 (rwx owner only) - Automatic permission enforcement on save

Implementation: save_token() in src/amplihack/proxy/github_auth.py

Security Audits & Reviews¶

Comprehensive security analysis:

• Neo4j Cleanup Security Audit - Memory system security review

Safe Operations¶

Guidelines for secure autonomous operations:

• Auto Mode Safety - Autonomous operation guardrails
• Passthrough Mode - Direct API access patterns

Configuration Security¶

Secure configuration practices:

• Profile Management - Secure environment configurations
• Proxy Configuration - Network security setup
• Hook Configuration - Secure hook customization

Azure & Cloud Security¶

Cloud deployment security:

• Azure Integration - Secure Azure deployment
• Test Azure Proxy - Validate secure proxy setup

Memory System Security¶

Securing agent memory and knowledge:

• Memory System Security - Memory security overview
• Neo4j Session Cleanup - Secure resource management

Testing Security Features¶

How to test and validate security implementations:

• Security Testing Guide - Complete testing guide
• Test coverage requirements: 90% minimum for security code
• Testing pyramid: 60% unit, 30% integration, 10% E2E

Run Security Tests:

# All security tests
pytest tests/proxy/test_security_sanitization.py -v

# With coverage
pytest tests/proxy/test_security_sanitization.py \
  --cov=amplihack.proxy.security \
  --cov-fail-under=90

Best Practices¶

Security principles and patterns:

• Development Philosophy - Security-first thinking
• Trust & Anti-Sycophancy - Honest, secure agent behavior
• Workflow Enforcement - Process security

Quick Security Checklist¶

Before deploying:

• Tokens sanitized in all log output
• Input validation on all external data
• Secure file permissions (0600/0700)
• Model names validated
• Error messages sanitized
• Security tests pass (90% coverage)

Related Documentation¶

• Troubleshooting - Security issue fixes
• Features - Feature-specific security
• Agents - Security agent

Security Issue Reporting¶

Found a security vulnerability? Report it:

1. DO NOT open a public GitHub issue
2. Email security issues to: [security contact TBD]
3. Include detailed reproduction steps
4. Allow 90 days for patch before disclosure

Security First: Always prioritize security over convenience. When in doubt, check Security Recommendations first.

New Features: PR #1925 (Issue #1922) added comprehensive token sanitization, model validation, input validation, and secure file permissions. See documentation links above for complete details.