ARCHITECTURE.md

Offensive Security Toolkit - Architecture

Overview

The Offensive Security Toolkit is a modular Python-based framework designed for authorized security testing and research. The architecture follows industry best practices aligned with the MITRE ATT&CK framework and modern penetration testing methodologies.

Design Principles

1. Modularity

• Each module is independent and can be used standalone or integrated
• Common utilities are centralized in the utils/ module
• Clear separation of concerns between reconnaissance, exploitation, and reporting

2. Security-First

• Authorization checks built into all tools
• Rate limiting to prevent abuse
• Comprehensive logging for audit trails
• Sensitive data never committed to version control

3. Extensibility

• Easy to add new modules and tools
• Plugin architecture for custom extensions
• Template-based tool development

4. Ethical Use

• Authorization validation before tool execution
• Clear warnings and disclaimers in all components
• Scope limitation enforced through configuration

Architecture Diagram

offensive-toolkit/
│
├── reconnaissance/         [MITRE: TA0043 Reconnaissance]
│   ├── __init__.py
│   ├── port_scanner.py    [T1046 Network Service Discovery]
│   ├── domain_enum.py     [T1590 Gather Victim Network Information]
│   └── osint_tools.py     [T1589 Gather Victim Identity Information]
│
├── scanning/              [MITRE: TA0043 Resource Development]
│   ├── __init__.py
│   ├── vuln_scanner.py    [T1595 Active Scanning]
│   └── service_enum.py    [T1046 Network Service Discovery]
│
├── exploitation/          [MITRE: TA0002 Execution]
│   ├── __init__.py
│   ├── reverse_shell.py   [T1059 Command and Scripting Interpreter]
│   └── exploit_db.py      [T1203 Exploitation for Client Execution]
│
├── post-exploitation/     [MITRE: Multiple Tactics]
│   ├── __init__.py
│   ├── lateral_move.py    [TA0008 Lateral Movement]
│   ├── persistence.py     [TA0003 Persistence]
│   └── exfiltration.py    [TA0010 Exfiltration]
│
├── social-engineering/    [MITRE: TA0001 Initial Access]
│   ├── __init__.py
│   └── phishing.py        [T1566 Phishing]
│
├── wireless/              [Wireless Attack Vectors]
│   ├── __init__.py
│   └── wifi_security.py
│
├── web-security/          [MITRE: TA0002 Execution - Web]
│   ├── __init__.py
│   ├── directory_bruteforcer.py [T1190 Exploit Public-Facing Application]
│   ├── sql_injection.py   [T1190 Exploit Public-Facing Application]
│   └── xss_scanner.py     [T1189 Drive-by Compromise]
│
├── payload-development/   [MITRE: TA0005 Defense Evasion]
│   ├── __init__.py
│   └── shellcode_gen.py   [T1027 Obfuscated Files or Information]
│
├── evasion/              [MITRE: TA0005 Defense Evasion]
│   ├── __init__.py
│   └── av_bypass.py       [T1562 Impair Defenses]
│
├── reporting/            [Documentation and Evidence]
│   ├── __init__.py
│   └── report_generator.py
│
└── utils/                [Common Utilities]
    ├── __init__.py
    ├── logger.py          [Centralized logging]
    ├── config.py          [Configuration management]
    └── helpers.py         [Common helper functions]

Module Descriptions

Reconnaissance Module

Purpose: Information gathering and OSINT MITRE Tactic: TA0043 (Reconnaissance)

Tools for passive and active information gathering:

• Port scanning and network discovery
• Domain enumeration and DNS reconnaissance
• Email harvesting and social media intelligence
• Subdomain enumeration

Scanning Module

Purpose: Vulnerability detection and service enumeration MITRE Tactic: TA0043 (Resource Development)

Tools for identifying vulnerabilities:

• Vulnerability scanning
• Service version detection
• Banner grabbing
• Security misconfiguration detection

Exploitation Module

Purpose: Exploit delivery and execution MITRE Tactic: TA0002 (Execution)

Frameworks and tools for:

• Custom exploit development
• Payload delivery mechanisms
• Reverse shell generation
• Privilege escalation techniques

Post-Exploitation Module

Purpose: Actions after initial compromise MITRE Tactics: TA0003 (Persistence), TA0008 (Lateral Movement), TA0010 (Exfiltration)

Tools for:

• Maintaining access and persistence
• Lateral movement within networks
• Credential dumping and harvesting
• Data exfiltration techniques

Social Engineering Module

Purpose: Human-factor testing MITRE Tactic: TA0001 (Initial Access)

Tools for:

• Phishing campaign creation and tracking
• Pretexting scenarios
• Physical security testing
• Awareness training simulations

Wireless Module

Purpose: Wireless security assessment Attack Vectors: WiFi, Bluetooth, RFID

Tools for:

• WiFi security testing (WPA/WPA2/WPA3)
• Bluetooth attack vectors
• Wireless protocol analysis

Web Security Module

Purpose: Web application security testing MITRE Tactic: TA0002 (Execution - Web)

Tools for testing:

• OWASP Top 10 vulnerabilities
• SQL injection detection
• Cross-site scripting (XSS)
• Directory traversal
• Authentication bypass

Payload Development Module

Purpose: Custom payload creation MITRE Tactic: TA0005 (Defense Evasion)

Tools for:

• Shellcode generation
• Payload obfuscation
• Encoder/decoder utilities
• Custom malware development (research only)

Evasion Module

Purpose: AV/EDR bypass techniques MITRE Tactic: TA0005 (Defense Evasion)

Tools for:

• Antivirus evasion
• EDR bypass techniques
• Process injection methods
• Code obfuscation

Reporting Module

Purpose: Documentation and evidence collection

Tools for:

• Automated report generation
• Findings documentation
• Evidence collection and chain of custody
• Integration with ticketing systems

Utils Module

Purpose: Common utilities and shared code

Provides:

• Centralized logging with rotation
• Configuration management (YAML/JSON)
• Helper functions (validation, rate limiting)
• Authorization checking
• Network utilities

Data Flow

Standard Tool Execution Flow

1. Configuration Loading
   └─> utils/config.py loads settings from config/config.yaml

2. Authorization Check
   └─> utils/helpers.py validates target against authorized list

3. Logging Initialization
   └─> utils/logger.py sets up logging to file and console

4. Tool Execution
   └─> Individual tool performs its function with rate limiting

5. Results Collection
   └─> Output saved to output/ directory

6. Report Generation
   └─> reporting/report_generator.py creates formatted reports

7. Cleanup
   └─> Temporary files removed, logs rotated

Configuration System

Configuration Hierarchy

1. Default Configuration: Hardcoded defaults in tool
2. Global Configuration: config/config.yaml
3. Tool-Specific Configuration: config/<tool>.yaml
4. Environment Variables: Override all other settings
5. Command-Line Arguments: Highest priority

Configuration Files

# config/config.yaml
logging:
  level: INFO
  file: logs/toolkit.log
  format: "[%(asctime)s] [%(levelname)s] %(message)s"

rate_limit:
  enabled: true
  requests_per_second: 10

timeouts:
  connection: 10
  read: 30

output:
  directory: output
  format: json

authorization:
  require_confirmation: true
  scope_file: config/authorized_targets.txt

Security Considerations

Authentication and Authorization

• All tools check config/authorized_targets.txt before execution
• Interactive confirmation required unless disabled
• Logging of all authorization checks

Rate Limiting

• Configurable rate limiting to prevent abuse
• Token bucket algorithm for request throttling
• Respect for robots.txt and rate limit headers

Logging and Audit Trail

• All actions logged with timestamps
• Log rotation to prevent disk space issues
• Sensitive data sanitized in logs
• Audit trail for compliance requirements

Data Protection

• Sensitive data encrypted at rest
• Credentials never logged in plain text
• Secure deletion of temporary files
• .gitignore prevents accidental commits

Extensibility

Adding New Modules

1. Create new directory under project root
2. Add __init__.py with module documentation
3. Implement tools following template pattern
4. Update docs/MITRE-MAPPING.md with MITRE ATT&CK mappings
5. Add tests in tests/ directory
6. Update README.md with usage examples

Tool Template Structure

#!/usr/bin/env python3
"""
Tool Name - Brief Description

[!] Authorization required before use
"""

import sys
from utils.logger import get_logger
from utils.config import load_config
from utils.helpers import validate_target, check_authorization

logger = get_logger(__name__)

class ToolName:
    def __init__(self, config=None):
        self.config = config or load_config()
        logger.info(f"Initialized {self.__class__.__name__}")

    def run(self, target):
        # Authorization check
        if not check_authorization(target):
            logger.error(f"Target {target} not authorized")
            return False

        # Tool implementation
        logger.info(f"Running {self.__class__.__name__} against {target}")
        # ... tool logic ...

        return True

if __name__ == "__main__":
    tool = ToolName()
    tool.run(sys.argv[1])

Testing Strategy

Unit Tests

• Test individual functions in isolation
• Mock external dependencies
• Coverage target: 80%+

Integration Tests

• Test module interactions
• Test configuration loading
• Test logging functionality

Security Tests

• Verify authorization checks work
• Test rate limiting enforcement
• Validate input sanitization

Ethical Testing

• No tests against live targets without authorization
• Use local test environments
• Isolated Docker containers for testing

Performance Considerations

Optimization Strategies

1. Asynchronous Operations: Use asyncio for concurrent operations
2. Connection Pooling: Reuse HTTP connections where possible
3. Caching: Cache DNS lookups and API responses
4. Batch Processing: Process multiple targets in batches
5. Resource Limits: Respect system resource constraints

Benchmarking

• Performance metrics logged for each tool
• Memory profiling for resource-intensive tools
• Execution time tracking

Deployment

Local Installation

git clone <repository>
cd offensive-toolkit
./setup.sh  # Linux/Mac
# or
.\setup.ps1  # Windows

Docker Deployment (Future)

# Planned: Dockerized deployment for isolated testing
FROM python:3.11-slim
WORKDIR /toolkit
COPY . .
RUN pip install -r requirements.txt
CMD ["/bin/bash"]

Future Enhancements

Planned Features

1. AI-Enhanced Testing: Machine learning for anomaly detection
2. Cloud Integration: Support for AWS, Azure, GCP security testing
3. C2 Framework: Command and control infrastructure
4. Mobile Security: Android and iOS security testing modules
5. Blockchain Security: Smart contract auditing tools
6. IoT Testing: IoT device security assessment
7. API Testing: RESTful and GraphQL API security
8. Container Security: Docker and Kubernetes security assessment

Integration Roadmap

• DefectDojo integration for vulnerability management
• JIRA integration for ticketing
• Slack/Teams notifications
• CI/CD pipeline integration
• SIEM integration for threat intelligence

References

• MITRE ATT&CK Framework
• OWASP Testing Guide
• PTES Technical Guidelines
• NIST Cybersecurity Framework

Compliance

This toolkit is designed to support:

• PCI DSS compliance testing
• HIPAA security assessments
• SOC 2 penetration testing
• ISO 27001 security audits
• GDPR security validation

---

Version: 0.1.0 Last Updated: 2025-10-15 Maintained By: David Dashti