# Security Module API Specification

**Version**: v1.1.9 | **Status**: Stable | **Last Updated**: February 2026

## 1. Overview
The `security` module is a comprehensive suite for digital, physical, and cognitive security operations. It integrates vulnerability scanning, secrets detection, access control, and compliance checking into a single unified API.

## 2. Core Components

### 2.1 Digital Security
- **Scanning**: `scan_vulnerabilities`, `scan_file_for_secrets`, `scan_directory_for_secrets`.
- **Auditing**: `audit_code_security`, `audit_secrets_exposure`, `audit_access_logs`.
- **Compliance**: `check_compliance(standard: ComplianceStandard)`.
- **Encryption**: `encrypt_sensitive_data`, `decrypt_sensitive_data`.
- **Certificates**: `validate_ssl_certificates`.
- **Reporting**: `generate_security_report`.

### 2.2 Physical Security (Optional)
- **Access Control**: `check_access_permission`, `grant_access`, `revoke_access`.
- **Asset Management**: `track_asset`, `register_asset`.
- **Surveillance**: `monitor_physical_access`.

### 2.3 Cognitive Security (Optional)
- **Social Engineering**: `detect_social_engineering`, `detect_phishing_attempt`.
- **Behavior Analysis**: `analyze_user_behavior`, `detect_anomalous_behavior`.
- **Training**: `create_training_module`.

### 2.4 Theory & Frameworks (Optional)
- **Threat Modeling**: `create_threat_model`, `analyze_threats`.
- **Risk Assessment**: `assess_risk`, `calculate_risk_score`.

## 3. Data Structures
- **`SecurityScanResult`**: Encapsulates findings from scans.
- **`VulnerabilityReport`**: Aggregated vulnerability data.
- **`SecurityIssue`**: Details of a specific finding.
- **`SecurityEvent`**: Record of a security-relevant occurrence.

## 4. Usage Example

```python
from codomyrmex.security import scan_directory_for_secrets, generate_security_report

# Scan for secrets
findings = scan_directory_for_secrets("./src")

# Generate report
report = generate_security_report(findings, format="json")
print(f"Found {len(findings)} potential secrets.")
```
