# Security Testing Guide - MyAIDev Method v0.2.21

**Security Module inspired by [Agent Zero](https://github.com/frdel/agent-zero)**

Complete guide to using MyAIDev Method's professional security testing capabilities.

## Table of Contents

1. [Introduction](#introduction)
2. [Legal and Ethical Requirements](#legal-and-ethical-requirements)
3. [Authorization System](#authorization-system)
4. [Environment Setup](#environment-setup)
5. [Security Workflows](#security-workflows)
6. [Security Agents](#security-agents)
7. [Security Commands](#security-commands)
8. [Best Practices](#best-practices)
9. [Compliance Framework](#compliance-frameworks)
10. [Troubleshooting](#troubleshooting)

---

## Introduction

MyAIDev Method v0.2.21 introduces enterprise-grade security testing capabilities for:

- **Penetration Testing** - Full PTES methodology implementation
- **OSINT & Reconnaissance** - Comprehensive intelligence gathering
- **Web Application Security** - OWASP Top 10 testing
- **Security Auditing** - Compliance validation (PCI-DSS, GDPR, HIPAA, SOC 2)
- **Professional Reporting** - Executive and technical reports

### Key Features

✅ **Authorization-First Security** - Mandatory authorization before any testing
✅ **Professional Methodologies** - PTES, OWASP, MITRE ATT&CK frameworks
✅ **Environment Flexibility** - Native Linux, Kali Docker, or hybrid
✅ **Comprehensive Tooling** - 50+ security testing tools
✅ **Professional Reporting** - Industry-standard report generation
✅ **Legal Compliance** - Built-in warnings and ethical guidelines

### Inspiration

The security module was inspired by the excellent [Agent Zero](https://github.com/frdel/agent-zero) project, adapted for MyAIDev Method's modular workflow architecture with enhanced authorization controls and compliance features.

---

## Legal and Ethical Requirements

### ⚠️ CRITICAL LEGAL WARNINGS

**UNAUTHORIZED SECURITY TESTING IS ILLEGAL**

- Testing without written authorization is a **federal crime** in most jurisdictions
- Criminal penalties include **imprisonment** and **substantial fines**
- Civil liability for **damages** caused by unauthorized testing
- Violations may include: Computer Fraud and Abuse Act (CFAA), Computer Misuse Act, etc.

### Authorization Requirements

**YOU MUST HAVE:**
1. ✅ Explicit written authorization from target owner
2. ✅ Defined scope of authorized targets
3. ✅ Clear authorization level (passive, active, exploitation)
4. ✅ Engagement timeline with start and end dates
5. ✅ Rules of engagement documented
6. ✅ Emergency contact information

**BEFORE:**
- Running ANY security commands
- Scanning ANY systems
- Testing ANY applications
- Gathering ANY intelligence

### Ethical Guidelines

**Professional Security Testing Standards:**

✅ **DO:**
- Obtain explicit written authorization before testing
- Stay within defined scope at all times
- Minimize disruption to target systems
- Report critical findings immediately
- Maintain confidentiality of findings
- Follow rules of engagement strictly
- Document all testing activities
- Respect privacy and data protection laws

❌ **DO NOT:**
- Test systems without authorization
- Exceed authorized testing scope
- Cause unnecessary disruption or damage
- Access more data than needed for PoC
- Share findings with unauthorized parties
- Use findings for personal gain
- Continue testing after engagement expires

---

## Authorization System

### Mandatory Authorization Framework

MyAIDev Method enforces authorization through `.security-authorization.json` manifest files.

**ALL security commands will:**
1. Check for authorization manifest before execution
2. Validate target is within authorized scope
3. Verify authorization level is sufficient
4. Ensure engagement dates are valid
5. Log all operations for audit purposes

### Creating Authorization Manifest

**Step 1: Generate Sample Manifest**

```bash
node src/scripts/security/create-auth-manifest.js
```

Or manually create `.security-authorization.json`:

```json
{
  "engagement_id": "ENG-2025-001",
  "client": "Client Company Name",
  "authorized_by": "John Smith (CTO)",
  "authorization_document": "signed_authorization_letter.pdf",
  "authorization_level": "exploitation",
  "scope": [
    {
      "type": "domain",
      "target": "*.example.com",
      "description": "All subdomains of example.com"
    },
    {
      "type": "ip_range",
      "target": "192.168.1.0/24",
      "description": "Internal network range"
    },
    {
      "type": "url",
      "target": "https://app.example.com",
      "description": "Web application"
    }
  ],
  "out_of_scope": [
    "production-db.example.com",
    "backup.example.com"
  ],
  "start_date": "2025-11-26",
  "end_date": "2025-12-26",
  "rules_of_engagement": {
    "testing_hours": "24/7",
    "exploit_depth": "full_exploitation_allowed",
    "data_exfiltration": "proof_of_concept_only",
    "service_disruption": "not_allowed",
    "social_engineering": "email_only",
    "physical_security": "not_authorized"
  },
  "contacts": {
    "primary": "security@example.com",
    "emergency": "+1-555-0123"
  },
  "reporting": {
    "critical_findings": "immediate_notification",
    "regular_updates": "weekly",
    "final_report": "within_5_days_of_completion"
  },
  "notes": "Penetration test authorized per signed agreement dated 2025-11-26"
}
```

### Authorization Levels

| Level | Description | Allowed Activities |
|-------|-------------|-------------------|
| **PASSIVE** | OSINT only | DNS lookups, WHOIS, public searches, certificate transparency |
| **ACTIVE** | Network scanning | Port scans, service enumeration, vulnerability scanning |
| **EXPLOITATION** | Full testing | PoC exploits, privilege escalation, data access validation |
| **INTERNAL** | Internal network | Lateral movement, internal reconnaissance, domain testing |

### Scope Types

**Supported Scope Types:**

1. **Domain** - `*.example.com` (wildcard subdomains)
2. **IP Range** - `192.168.1.0/24` (CIDR notation)
3. **URL** - `https://app.example.com` (specific URLs)
4. **Network** - `internal-network` (network identifiers)
5. **Application** - `customer-portal` (application names)

### Validation Example

```javascript
import { requireAuthorization, AuthLevel } from './src/libs/security/authorization-checker.js';

// Check authorization before testing
const target = 'app.example.com';
await requireAuthorization(target, AuthLevel.ACTIVE);

// If authorized, proceed with testing
// If not authorized, command will terminate with error
```

---

## Environment Setup

### Supported Environments

MyAIDev Method security testing supports multiple deployment scenarios:

1. **Native Linux** - VPS, dedicated server, or workstation
2. **Kali Linux Docker** - Isolated container environment
3. **Kali Linux Native** - Pre-configured penetration testing OS
4. **Hybrid** - Combination of native and containerized tools

### Environment Detection

**Automatically detect your environment:**

```bash
node src/scripts/security/environment-detect.js
```

**Output:**
```
🔍 Detecting security testing environment...

═══════════════════════════════════════════════════════
🔍 Environment Detection Results
═══════════════════════════════════════════════════════

📋 Operating System:
   Name: Ubuntu
   Version: 25.04 (Plucky Puffin)
   Kernel: 6.14.0-28-generic
   Package Manager: apt

🐳 Container Environment:
   Docker Available: Yes
   Docker Running: Yes

═══════════════════════════════════════════════════════
📋 Recommended Setup Approach
═══════════════════════════════════════════════════════

✨ Approach: KALI DOCKER
📝 Reason: Docker available - isolated environment recommended
⏱️  Estimated Time: 20-30 minutes
💾 Disk Space: ~3GB
```

### Installation Methods

#### Method 1: Kali Linux Docker (Recommended)

**Advantages:**
- Isolated testing environment
- No impact on host system
- Easy to manage and update
- All tools pre-installed in Kali

**Setup:**

```bash
# 1. Pull Kali Linux image
docker pull kalilinux/kali-rolling

# 2. Create persistent volume
docker volume create kali-data

# 3. Start Kali container
docker run -it \
  --name kali-pentest \
  --hostname kali \
  --network host \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  -v kali-data:/root \
  -v $(pwd):/workspace \
  kalilinux/kali-rolling /bin/bash

# 4. Inside container, update and install tools
apt update && apt upgrade -y
apt install -y kali-linux-default

# 5. Install additional tools as needed
apt install -y metasploit-framework burpsuite zaproxy
```

**Access MyAIDev Method from Kali container:**
```bash
cd /workspace
npm install
/sc:security-setup
```

#### Method 2: Native Linux Installation

**For Ubuntu/Debian:**

```bash
# 1. Update system
sudo apt update && sudo apt upgrade -y

# 2. Install security tools
/sc:security-setup --native

# This will install:
# - Network scanning (nmap, masscan)
# - Web testing (nikto, sqlmap, wpscan)
# - Exploitation (metasploit-framework)
# - Password tools (john, hashcat, hydra)
# - OSINT (theHarvester, recon-ng)
```

**For Fedora/RHEL:**

```bash
# 1. Enable EPEL repository
sudo dnf install epel-release -y

# 2. Install security tools
/sc:security-setup --native-fedora
```

#### Method 3: Kali Linux Native

**If already running Kali Linux:**

```bash
# 1. Verify tools installed
/sc:security-setup --verify

# 2. Install missing tools
/sc:security-setup --update

# 3. Ready to use security commands
/sc:security-recon example.com
```

### Tool Verification

**Check installed security tools:**

```bash
# Verify essential tools
which nmap masscan sqlmap nikto hydra john metasploit-framework

# Check versions
nmap --version
msfconsole --version
sqlmap --version
```

---

## Security Workflows

MyAIDev Method v0.2.21 includes three security testing workflows:

### 1. Penetration Testing Workflow

**Full-scope security assessment following PTES methodology**

```bash
# Install penetration testing workflow
npx myaidev-method@latest security --pentest

# Or using npm
npm install -g myaidev-method@latest
myaidev-method security --pentest
```

**Included:**
- 🔍 OSINT & Reconnaissance
- 🌐 Network & Service Scanning
- 🎯 Exploitation Testing
- 🚀 Post-Exploitation
- 📊 Professional Reporting

**Agents:**
- security-setup
- penetration-tester
- osint-researcher

**Commands:**
- /sc:security-setup
- /sc:security-recon
- /sc:security-scan
- /sc:security-exploit
- /sc:security-report

### 2. Security Audit Workflow

**Compliance validation and defensive security**

```bash
# Install security audit workflow
npx myaidev-method@latest security --audit
```

**Included:**
- 🔒 Infrastructure Security Assessment
- ✅ Compliance Validation (PCI-DSS, GDPR, HIPAA, SOC 2)
- 🛡️ System Hardening Review
- 📋 Policy & Configuration Audit
- 📈 Vulnerability Management

**Agents:**
- security-setup
- security-auditor

**Focus Areas:**
- PCI-DSS Requirements
- GDPR Data Protection
- HIPAA Technical Safeguards
- SOC 2 Trust Services
- ISO 27001 Controls

### 3. Web Application Security Workflow

**OWASP Top 10 focused web security testing**

```bash
# Install web application security workflow
npx myaidev-method@latest security --webapp
```

**Included:**
- 🌐 Web Application Testing
- 🔍 OWASP Top 10 2021
- 🔐 Authentication & Authorization Testing
- 💉 Injection Testing (SQLi, XSS, XXE)
- 🛡️ Security Configuration Review

**Agents:**
- security-setup
- webapp-security-tester

**OWASP Coverage:**
- A01:2021 - Broken Access Control
- A02:2021 - Cryptographic Failures
- A03:2021 - Injection
- A04:2021 - Insecure Design
- A05:2021 - Security Misconfiguration
- A06:2021 - Vulnerable Components
- A07:2021 - Authentication Failures
- A08:2021 - Data Integrity Failures
- A09:2021 - Logging & Monitoring Failures
- A10:2021 - SSRF

### Install All Security Workflows

```bash
# Install complete security module
npx myaidev-method@latest security --all
```

---

## Security Agents

### 1. security-setup

**Environment detection and tool installation agent**

**Purpose:**
- Detect execution environment (native, Docker, Kali)
- Recommend optimal setup approach
- Install and configure security tools
- Verify tool installations

**Usage:**
```bash
/sc:security-setup
```

**Capabilities:**
- Environment detection (OS, container, Docker)
- Tool installation automation
- Kali Docker container management
- Installation verification

### 2. penetration-tester

**Elite penetration testing agent following PTES methodology**

**Purpose:**
- Conduct comprehensive penetration tests
- Execute exploitation operations
- Perform post-exploitation activities
- Generate professional reports

**Methodology:**
- Pre-Engagement
- Intelligence Gathering
- Threat Modeling
- Vulnerability Analysis
- Exploitation
- Post-Exploitation
- Reporting

**Frameworks:**
- PTES (Penetration Testing Execution Standard)
- MITRE ATT&CK
- OWASP Testing Guide
- NIST SP 800-115

### 3. osint-researcher

**OSINT and reconnaissance specialist**

**Purpose:**
- Passive intelligence gathering
- Subdomain discovery
- Email harvesting
- Technology stack identification
- Search engine intelligence

**Techniques:**
- DNS enumeration
- WHOIS intelligence
- Certificate transparency
- Google dorking
- Shodan queries
- Social media intelligence
- Code repository analysis

### 4. webapp-security-tester

**Web application security testing with OWASP focus**

**Purpose:**
- OWASP Top 10 testing
- Authentication/authorization testing
- Input validation testing
- Session management review
- Security header validation

**Testing Areas:**
- Injection vulnerabilities
- Broken authentication
- Sensitive data exposure
- XML external entities
- Broken access control
- Security misconfiguration
- Cross-site scripting (XSS)
- Insecure deserialization
- Components with known vulnerabilities
- Insufficient logging & monitoring

### 5. security-auditor

**Compliance validation and security auditing specialist**

**Purpose:**
- Compliance framework validation
- Infrastructure security assessment
- Access control review
- Security configuration audit
- Compliance reporting

**Frameworks:**
- PCI-DSS (Payment Card Industry)
- GDPR (Data Protection)
- HIPAA (Healthcare)
- SOC 2 (Service Organizations)
- ISO 27001 (Information Security)
- NIST Cybersecurity Framework

---

## Security Commands

### /sc:security-setup

**Complete security environment setup**

```bash
# Auto-detect and setup environment
/sc:security-setup

# Force native installation
/sc:security-setup --native

# Setup Kali Docker container
/sc:security-setup --kali-docker

# Verify existing installation
/sc:security-setup --verify
```

**Workflow:**
1. Detect environment (OS, container, Docker)
2. Recommend setup approach
3. Install required tools
4. Configure environment
5. Verify installations

### /sc:security-recon

**OSINT and reconnaissance operations**

```bash
# Basic reconnaissance
/sc:security-recon example.com

# Focus on subdomains
/sc:security-recon example.com --focus subdomains

# Email harvesting
/sc:security-recon example.com --focus emails
```

**Authorization Level:** PASSIVE (no direct target interaction)

**Activities:**
- DNS intelligence
- WHOIS data
- Subdomain discovery
- Email harvesting
- Technology detection
- Search engine intelligence
- Certificate transparency

**Output:** Intelligence report saved to `reports/osint-example.com-[DATE].md`

### /sc:security-scan

**Active network and service scanning**

```bash
# Network scan
/sc:security-scan 192.168.1.0/24

# Single host deep scan
/sc:security-scan 192.168.1.10 --deep

# Web application scan
/sc:security-scan https://app.example.com --web
```

**Authorization Level:** ACTIVE (network interaction allowed)

**Activities:**
- Host discovery
- Port scanning (TCP/UDP)
- Service enumeration
- OS detection
- Vulnerability scanning
- SSL/TLS analysis

**Output:** Scan report saved to `reports/scan-[TARGET]-[DATE].md`

### /sc:security-exploit

**Exploitation operations (CRITICAL - Requires explicit authorization)**

```bash
# Web application exploitation
/sc:security-exploit https://app.example.com --sqli

# Network service exploitation
/sc:security-exploit 192.168.1.50 --service smb

# Privilege escalation testing
/sc:security-exploit 192.168.1.10 --privesc
```

**Authorization Level:** EXPLOITATION (full testing authorized)

⚠️ **WARNING:** This command executes active exploitation. Ensure explicit written authorization.

**Activities:**
- Vulnerability validation
- Proof-of-concept exploitation
- Post-exploitation (if authorized)
- Evidence collection
- Immediate critical finding reporting
- System cleanup

**Output:** Exploitation report saved to `reports/exploitation-[TARGET]-[DATE].md`

### /sc:security-report

**Professional security assessment report generation**

```bash
# Generate executive report
/sc:security-report --executive --engagement ENG-2025-001

# Generate technical report
/sc:security-report --technical --engagement ENG-2025-001

# Quick assessment summary
/sc:security-report --quick
```

**Report Types:**
1. **Executive Summary** - C-level, non-technical
2. **Technical Report** - IT/Security teams, detailed findings
3. **Remediation Plan** - Prioritized action items
4. **Compliance Report** - Regulatory framework validation
5. **Quick Assessment** - Rapid overview

**Output:** Professional reports in `reports/` directory

---

## Best Practices

### Pre-Engagement

✅ **ALWAYS:**
1. Obtain explicit written authorization
2. Define clear scope with client
3. Create `.security-authorization.json` manifest
4. Verify authorization manifest is valid
5. Establish communication protocols
6. Define rules of engagement
7. Set up emergency contacts

### During Testing

✅ **DO:**
- Stay within authorized scope
- Minimize system disruption
- Document all activities
- Report critical findings immediately
- Follow rules of engagement
- Maintain professional conduct
- Log all operations

❌ **DON'T:**
- Test unauthorized targets
- Cause unnecessary disruption
- Access more data than needed
- Share findings with unauthorized parties
- Continue after engagement expires

### Reporting

✅ **INCLUDE:**
- Executive summary (non-technical)
- Technical findings (detailed)
- Proof of concept evidence
- CVSS scores for vulnerabilities
- Business impact assessment
- Prioritized remediation roadmap
- Compliance mapping (if applicable)

### Post-Engagement

✅ **COMPLETE:**
1. Final comprehensive report
2. Evidence package delivery
3. Client debriefing/presentation
4. Remediation support (if contracted)
5. Secure deletion of client data
6. Archive engagement documentation

---

## Compliance Frameworks

### PCI-DSS (Payment Card Industry Data Security Standard)

**Key Requirements Tested:**

**Requirement 1:** Install and Maintain Firewall
- Network segmentation validation
- Firewall rule review
- DMZ configuration assessment

**Requirement 2:** No Default Passwords
- Default credential testing
- Password policy review
- Strong authentication validation

**Requirement 3:** Protect Stored Cardholder Data
- Encryption verification
- PAN truncation/masking
- Key management review

**Requirement 10:** Track and Monitor Network Access
- Logging implementation review
- Access monitoring validation
- Audit trail assessment

**Agent:** security-auditor

### GDPR (General Data Protection Regulation)

**Data Protection Principles:**

1. **Lawfulness, Fairness, Transparency**
   - Legal basis verification
   - Privacy notice review
   - Data subject rights validation

2. **Purpose Limitation**
   - Data usage assessment
   - Secondary use validation

3. **Data Minimization**
   - Data collection review
   - Retention policy assessment

4. **Accountability**
   - Documentation review
   - DPIA (Data Protection Impact Assessment) validation

**Agent:** security-auditor

### HIPAA (Health Insurance Portability and Accountability Act)

**Technical Safeguards:**

1. **Access Control**
   - Unique user identification
   - Emergency access procedures
   - Automatic logoff
   - Encryption/decryption

2. **Audit Controls**
   - Activity recording
   - ePHI access logging

3. **Transmission Security**
   - ePHI encryption in transit
   - Network controls

**Agent:** security-auditor

### SOC 2 (Service Organization Control)

**Trust Services Criteria:**

1. **Security**
   - Security policies and procedures
   - Risk assessment
   - Monitoring

2. **Availability**
   - System availability commitments
   - Backup and recovery

**Agent:** security-auditor

---

## Troubleshooting

### Authorization Errors

**Error: "Authorization manifest not found"**
```
❌ Authorization manifest not found at .security-authorization.json

CRITICAL: Security testing requires explicit authorization.
Create .security-authorization.json with proper authorization details.
```

**Solution:**
```bash
# Create authorization manifest
cp .security-authorization.example.json .security-authorization.json

# Edit with your engagement details
nano .security-authorization.json
```

**Error: "Target not in authorized scope"**
```
❌ Target not in authorized scope: app.example.com

Authorized scope:
  - *.testing.example.com
  - 192.168.100.0/24

This target is NOT authorized for testing.
```

**Solution:**
- Verify target is correct
- Add target to `.security-authorization.json` scope
- Obtain additional authorization if needed

**Error: "Insufficient authorization level"**
```
❌ Insufficient authorization level.

Required: EXPLOITATION
Current: ACTIVE

This operation requires higher authorization level.
```

**Solution:**
- Update `authorization_level` in `.security-authorization.json`
- Obtain higher authorization from client
- Use commands appropriate for current level

### Environment Issues

**Error: "Docker not available"**

**Solution:**
```bash
# Install Docker
curl -fsSL https://get.docker.com | sh

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Verify installation
docker --version
docker ps
```

**Error: "Security tools not installed"**

**Solution:**
```bash
# Run environment detection
node src/scripts/security/environment-detect.js

# Follow recommended setup approach
/sc:security-setup
```

### Tool Errors

**Error: "nmap command not found"**

**Solution:**
```bash
# Ubuntu/Debian
sudo apt install nmap

# Fedora/RHEL
sudo dnf install nmap

# Or use Kali Docker
docker run -it kalilinux/kali-rolling
apt update && apt install -y kali-linux-default
```

**Error: "Metasploit not working"**

**Solution:**
```bash
# Initialize Metasploit database
msfdb init

# Update Metasploit
msfupdate

# Start Metasploit
msfconsole
```

---

## Additional Resources

### Documentation

- [SECURITY_MODULE_PLAN.md](./SECURITY_MODULE_PLAN.md) - Complete architecture plan
- [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) - Implementation details
- [README.md](./README.md) - Package overview

### External Resources

**Security Frameworks:**
- [PTES Technical Guidelines](http://www.pentest-standard.org/index.php/Main_Page)
- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/)
- [MITRE ATT&CK](https://attack.mitre.org/)
- [NIST SP 800-115](https://csrc.nist.gov/publications/detail/sp/800-115/final)

**Compliance:**
- [PCI-DSS Requirements](https://www.pcisecuritystandards.org/)
- [GDPR Official Text](https://gdpr.eu/)
- [HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html)
- [SOC 2 Trust Services](https://www.aicpa.org/soc)

**Inspiration:**
- [Agent Zero](https://github.com/frdel/agent-zero) - Original inspiration for security module

### Community and Support

- **GitHub Issues:** [myaidev-method/issues](https://github.com/myaione/myaidev-method/issues)
- **Security Discussion:** Use GitHub Discussions for security-related questions
- **Bug Reports:** Report security bugs responsibly via GitHub Security Advisories

---

## Legal Disclaimer

This security testing module is provided for **authorized security testing only**. Users are solely responsible for:

1. Obtaining proper written authorization before testing
2. Compliance with all applicable laws and regulations
3. Staying within authorized scope
4. Following ethical guidelines and professional standards
5. Respecting privacy and data protection laws

**The developers and contributors of MyAIDev Method:**
- Do NOT authorize or condone unauthorized security testing
- Are NOT responsible for misuse of security testing capabilities
- Do NOT provide legal advice or authorization
- Recommend consulting legal counsel for authorization requirements

**USE AT YOUR OWN RISK. UNAUTHORIZED TESTING IS ILLEGAL AND PROSECUTABLE.**

---

**Version:** 1.0.0 (v0.2.21)
**Last Updated:** 2025-11-26
**Security Module:** Inspired by [Agent Zero](https://github.com/frdel/agent-zero)