initial commit

Signed-off-by: ale <ale@manalejandro.com>
Este commit está contenido en:
ale
2025-11-16 17:20:37 +01:00
commit 9bf87efb79
Se han modificado 18 ficheros con 3435 adiciones y 0 borrados

408
docs/ARCHITECTURE.md Archivo normal
Ver fichero

@@ -0,0 +1,408 @@
# ActivityPub Security PoC - Architecture
## Project Structure
```
activitypub-security-poc/
├── src/
│ ├── cli.js # Command-line interface
│ ├── activitypub-client.js # ActivityPub HTTP client
│ ├── security-tester.js # Security testing module
│ └── mock-server.js # Mock ActivityPub server
├── examples/
│ ├── create-note.json # Sample Create activity
│ ├── follow.json # Sample Follow activity
│ ├── xss-payload.json # XSS test payload
│ ├── ssrf-payload.json # SSRF test payload
│ └── USAGE.md # Usage examples
├── docs/
│ ├── ARCHITECTURE.md # This file
│ └── SECURITY_TESTING.md # Security testing guide
├── package.json
├── README.md
└── test.sh # Quick test script
```
## Core Components
### 1. ActivityPub Client (`activitypub-client.js`)
**Purpose**: Low-level HTTP client for ActivityPub interactions.
**Key Features**:
- Send activities to inbox endpoints
- Fetch from outbox endpoints
- Fetch actor profiles
- HTTP signature generation (for authenticated requests)
- JSON-LD context handling
- Activity creation helpers
**Main Methods**:
```javascript
class ActivityPubClient {
sendToInbox(inboxUrl, activity, options)
fetchOutbox(outboxUrl, options)
fetchActor(actorUrl, options)
signRequest(method, url, body)
createActivity(type, object, additionalProps)
createNote(content, additionalProps)
}
```
### 2. Security Tester (`security-tester.js`)
**Purpose**: Automated security testing framework.
**Key Features**:
- XSS vulnerability testing
- SSRF vulnerability testing
- Object injection testing
- Signature bypass testing
- Authorization testing
- SQL/Command injection testing
**Main Methods**:
```javascript
class SecurityTester {
testXSS(inboxUrl)
testSSRF(inboxUrl)
testObjectInjection(inboxUrl)
testSignatureBypass(inboxUrl)
testAuthorization(actorUrl, inboxUrl)
testInjection(inboxUrl)
runAllTests(targetUrl, options)
generateReport(results)
}
```
### 3. CLI (`cli.js`)
**Purpose**: User-friendly command-line interface.
**Commands**:
- `test-inbox` - Send activities to inbox
- `test-outbox` - Fetch from outbox
- `fetch-actor` - Get actor profile
- `security-scan` - Run security tests
- `craft` - Create custom activities
- `mock-server` - Start mock server
### 4. Mock Server (`mock-server.js`)
**Purpose**: Simulated ActivityPub server for testing.
**Key Features**:
- Full ActivityPub endpoint simulation
- WebFinger support
- Activity validation
- Security issue detection and logging
- Multiple mock users (alice, bob)
**Endpoints**:
- `/.well-known/webfinger` - WebFinger
- `/users/:username` - Actor profiles
- `/users/:username/inbox` - User inbox
- `/users/:username/outbox` - User outbox
- `/users/:username/followers` - Followers collection
- `/users/:username/following` - Following collection
- `/inbox` - Shared inbox
## Data Flow
### Sending an Activity
```
User Command
CLI (cli.js)
ActivityPubClient.sendToInbox()
HTTP POST with JSON-LD payload
Target Server (or Mock Server)
Response (status, headers, body)
Display to User
```
### Security Scan
```
User Command
CLI (cli.js)
SecurityTester.runAllTests()
Multiple Test Methods (XSS, SSRF, etc.)
ActivityPubClient.sendToInbox() for each payload
Collect responses
Analyze for vulnerabilities
Generate Report
Display to User
```
### Mock Server Request Handling
```
HTTP Request
MockActivityPubServer.handleRequest()
Route to appropriate handler
Validate activity (if POST)
Perform security checks
Log detected issues
Store activity (if valid)
Return response
```
## Security Testing Methodology
### 1. Test Case Design
Each security test:
1. Creates a malicious payload
2. Sends it to the target endpoint
3. Analyzes the response
4. Determines if vulnerability exists based on:
- Response status (200/202 = potential issue)
- Error messages
- Behavior changes
### 2. Payload Categories
**XSS Payloads**:
- Script tags
- Event handlers
- JavaScript protocols
- SVG-based vectors
- Encoded payloads
**SSRF Payloads**:
- Internal IPs (localhost, 127.0.0.1)
- Cloud metadata endpoints
- File protocol URLs
- IPv6 localhost
- DNS rebinding targets
**Injection Payloads**:
- SQL injection patterns
- Command injection sequences
- Prototype pollution attempts
- Path traversal strings
### 3. Validation Logic
The mock server demonstrates proper validation:
```javascript
// Activity validation
validateActivity(activity) {
- Check for required fields
- Validate @context
- Verify actor field
- Return validation result
}
// Security checks
performSecurityChecks(activity) {
- Scan for XSS patterns
- Check for SSRF attempts
- Detect prototype pollution
- Identify SQL injection patterns
- Return list of issues
}
```
## HTTP Signatures (Planned)
Future versions will implement full HTTP signature support:
```
1. Generate RSA key pair
2. Include public key in actor profile
3. Sign requests with private key
4. Verify signatures on mock server
5. Test signature bypass scenarios
```
## Extension Points
### Adding New Security Tests
1. Add test method to `SecurityTester`:
```javascript
async testNewVulnerability(inboxUrl) {
const payloads = [...];
const results = [];
for (const payload of payloads) {
// Create activity with payload
// Send to inbox
// Analyze response
results.push({...});
}
return results;
}
```
2. Integrate into `runAllTests()`:
```javascript
if (!options.tests || options.tests.includes('newvuln')) {
allResults.tests.newVuln = await this.testNewVulnerability(targetUrl);
}
```
### Adding New CLI Commands
1. Add command to `cli.js`:
```javascript
program
.command('new-command')
.description('Description')
.option('-f, --flag <value>', 'Option')
.action(async (options) => {
// Implementation
});
```
### Extending Mock Server
1. Add new endpoint handler:
```javascript
async handleNewEndpoint(req, res, path) {
// Handle request
this.sendJSON(res, data);
}
```
2. Add route in `handleRequest()`:
```javascript
if (path.match(/^\/new-endpoint$/)) {
await this.handleNewEndpoint(req, res, path);
}
```
## Best Practices
### Code Organization
- **Separation of Concerns**: Client, tester, CLI, and server are separate modules
- **Reusability**: Core client can be used independently
- **Extensibility**: Easy to add new tests or commands
- **Clean Code**: Well-commented, readable, maintainable
### Error Handling
- Graceful error handling in all HTTP requests
- Informative error messages
- Non-blocking errors (continue testing on failure)
### Logging
- Clear console output with color coding
- Structured JSON output for results
- Detailed mock server logs for debugging
### Testing Philosophy
- **Defense in Depth**: Test multiple vulnerability types
- **Real-world Scenarios**: Payloads based on actual attacks
- **Responsible Testing**: Tools designed for authorized testing only
- **Educational**: Code demonstrates both vulnerabilities and mitigations
## Future Enhancements
### Planned Features
1. **Full HTTP Signature Support**
- RSA key generation
- Signature creation and verification
- Key rotation testing
2. **WebFinger Testing**
- Account discovery
- Resource validation
- SSRF via WebFinger
3. **Media Upload Testing**
- File upload vulnerabilities
- Content-Type confusion
- Malicious file detection bypass
4. **Rate Limiting Tests**
- Concurrent request flooding
- Activity spam detection
- Resource exhaustion
5. **Interactive Mode**
- Step-by-step testing wizard
- Real-time response analysis
- Guided security audits
6. **CI/CD Integration**
- GitHub Actions workflow
- Automated regression testing
- Security benchmarking
7. **Reporting**
- HTML report generation
- PDF export
- Vulnerability database integration
## Performance Considerations
- **Async Operations**: All HTTP requests are asynchronous
- **Timeout Handling**: Configurable timeouts prevent hanging
- **Resource Management**: Proper cleanup of connections
- **Scalability**: Can test multiple endpoints in parallel
## Security Considerations
### Tool Security
- No sensitive data storage
- No persistent state by default
- Safe defaults (localhost, low timeout)
- Clear warnings about authorized testing
### Mock Server Security
- Intentionally logs security issues (for demonstration)
- Does not execute malicious payloads
- Sandboxed environment
- No real persistence
## Dependencies
- **commander**: CLI argument parsing
- **node-fetch**: HTTP client
- **chalk**: Terminal colors
- **jsonld**: JSON-LD processing
- **http-signature**: HTTP signature support (planned)
All dependencies are well-maintained and security-audited.
## Contribution Guidelines
When extending this project:
1. **Follow the architecture**: Keep separation of concerns
2. **Add tests**: Include example payloads
3. **Document**: Update this file and other docs
4. **Clean code**: Follow existing style
5. **Security first**: Consider implications of new features

345
docs/SECURITY_TESTING.md Archivo normal
Ver fichero

@@ -0,0 +1,345 @@
# Security Testing Guide
## Overview
This document outlines the security testing methodology and test cases for ActivityPub implementations.
## Security Test Categories
### 1. Cross-Site Scripting (XSS)
**Objective**: Identify if user-supplied content is properly sanitized before display.
**Test Cases**:
- Script tag injection: `<script>alert('XSS')</script>`
- Event handler injection: `<img src=x onerror=alert('XSS')>`
- JavaScript protocol: `javascript:alert('XSS')`
- SVG-based XSS: `<svg/onload=alert('XSS')>`
- Encoded payloads: `&#60;script&#62;alert('XSS')&#60;/script&#62;`
**Vulnerable Scenarios**:
- Content rendered without HTML escaping
- Markdown/rich text processing vulnerabilities
- URL handling in attachment previews
### 2. Server-Side Request Forgery (SSRF)
**Objective**: Test if the server can be tricked into making requests to internal resources.
**Test Cases**:
- Internal network: `http://localhost:8080`, `http://127.0.0.1`
- Cloud metadata: `http://169.254.169.254/latest/meta-data/`
- IPv6 localhost: `http://[::1]:8080`
- File protocol: `file:///etc/passwd`
- DNS rebinding attacks
**Vulnerable Scenarios**:
- Fetching remote avatars/images without validation
- Link previews/unfurling
- WebFinger lookups without URL validation
### 3. Object Injection & Type Confusion
**Objective**: Test object validation and type handling.
**Test Cases**:
- Multiple type values: `"type": ["Note", "Delete"]`
- Missing required fields
- Prototype pollution: `__proto__` injection
- Constructor manipulation
- Unexpected nested objects
**Vulnerable Scenarios**:
- Weak JSON schema validation
- Dynamic property assignment
- Type coercion vulnerabilities
### 4. Authentication & Authorization
**Objective**: Verify proper access controls and signature verification.
**Test Cases**:
- Missing HTTP signatures
- Invalid/forged signatures
- Actor impersonation
- Unauthorized deletions
- Private content access
- Relay poisoning
**Vulnerable Scenarios**:
- Weak signature verification
- Missing authorization checks
- Confused deputy attacks
### 5. Injection Attacks
**Objective**: Test for command and SQL injection vulnerabilities.
**Test Cases**:
- SQL injection: `' OR '1'='1`, `'; DROP TABLE--`
- Command injection: `; ls -la`, `| whoami`, `$(uname -a)`
- LDAP injection
- Template injection
- Path traversal: `../../etc/passwd`
**Vulnerable Scenarios**:
- Direct database queries with user input
- System command execution
- Template rendering with user content
### 6. Denial of Service (DoS)
**Objective**: Test resilience against resource exhaustion.
**Test Cases**:
- Large payloads (MB-sized JSON)
- Deeply nested objects
- Circular references
- Excessive followers/following counts
- Rapid activity submission
**Vulnerable Scenarios**:
- No rate limiting
- Unbounded resource allocation
- Inefficient parsing
## Testing Methodology
### 1. Reconnaissance
```bash
# Fetch actor profile
node src/cli.js fetch-actor --target https://target.example/users/alice
# Check outbox
node src/cli.js test-outbox --target https://target.example/users/alice/outbox
```
### 2. Baseline Testing
```bash
# Send valid activity
node src/cli.js test-inbox \
--target https://target.example/users/alice/inbox \
--payload examples/create-note.json
```
### 3. Automated Security Scan
```bash
# Run all tests
node src/cli.js security-scan \
--target https://target.example/users/alice/inbox \
--output scan-results.json
```
### 4. Manual Payload Testing
```bash
# Test specific vulnerability
node src/cli.js test-inbox \
--target https://target.example/users/alice/inbox \
--payload examples/xss-payload.json
```
### 5. Analysis
Review logs, responses, and behavior:
- HTTP status codes
- Error messages
- Server-side rendering
- Database queries
- Network traffic
## Responsible Disclosure
If you discover a vulnerability:
1. **Do not exploit** beyond proof-of-concept
2. **Document** the issue thoroughly
3. **Report privately** to the maintainers
4. **Allow time** for fixes (typically 90 days)
5. **Coordinate** public disclosure
## Common Vulnerabilities in ActivityPub
### 1. Inadequate Input Validation
```javascript
// Vulnerable
app.post('/inbox', (req, res) => {
const activity = req.body;
db.query(`INSERT INTO activities VALUES ('${activity.id}')`); // SQL injection
});
// Secure
app.post('/inbox', (req, res) => {
const activity = req.body;
if (!validateActivitySchema(activity)) {
return res.status(400).send('Invalid activity');
}
db.query('INSERT INTO activities VALUES (?)', [activity.id]);
});
```
### 2. Missing Signature Verification
```javascript
// Vulnerable
app.post('/inbox', (req, res) => {
// No signature check
processActivity(req.body);
});
// Secure
app.post('/inbox', async (req, res) => {
if (!await verifyHTTPSignature(req)) {
return res.status(401).send('Invalid signature');
}
processActivity(req.body);
});
```
### 3. SSRF in Media Fetching
```javascript
// Vulnerable
async function fetchAvatar(url) {
return await fetch(url); // No URL validation
}
// Secure
async function fetchAvatar(url) {
const parsed = new URL(url);
// Block internal IPs
if (isInternalIP(parsed.hostname)) {
throw new Error('Invalid URL');
}
// Only allow http/https
if (!['http:', 'https:'].includes(parsed.protocol)) {
throw new Error('Invalid protocol');
}
return await fetch(url, { redirect: 'manual' });
}
```
### 4. Unescaped Content Rendering
```javascript
// Vulnerable
function renderNote(note) {
return `<div>${note.content}</div>`; // XSS
}
// Secure
function renderNote(note) {
const escaped = escapeHtml(note.content);
return `<div>${escaped}</div>`;
}
```
## Security Checklist
- [ ] HTTP signatures verified on all inbox POST requests
- [ ] Actor URLs validated (no internal IPs, valid protocols)
- [ ] Content sanitized before display (HTML escaping)
- [ ] Rate limiting on endpoints
- [ ] JSON schema validation
- [ ] Authorization checks on Delete/Update activities
- [ ] SSRF protection on media fetching
- [ ] Proper error handling (no sensitive info in errors)
- [ ] CSRF protection
- [ ] Content Security Policy headers
- [ ] Input size limits
- [ ] Secure session management
## Tools & Resources
### Testing Tools
- This ActivityPub Security PoC
- Burp Suite
- OWASP ZAP
- curl/httpie
### References
- [ActivityPub Specification](https://www.w3.org/TR/activitypub/)
- [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [Fediverse Security Best Practices](https://github.com/w3c/activitypub/issues/367)
## Reporting Format
When reporting issues, include:
1. **Title**: Brief description
2. **Severity**: Critical/High/Medium/Low
3. **Description**: What the vulnerability is
4. **Steps to Reproduce**: Detailed reproduction steps
5. **Impact**: What an attacker could do
6. **Proof of Concept**: Code/payload demonstrating the issue
7. **Remediation**: Suggested fix
8. **References**: Related CVEs, articles
### Example Report
```markdown
## XSS in Note Content
**Severity**: High
**Description**: User-supplied content in Note objects is rendered without HTML escaping, allowing arbitrary JavaScript execution.
**Steps to Reproduce**:
1. Send Create activity with XSS payload in content field
2. View the note in web interface
3. Observe JavaScript execution
**Impact**: Account takeover, data theft, malware distribution
**Proof of Concept**:
```json
{
"type": "Create",
"object": {
"type": "Note",
"content": "<script>alert(document.cookie)</script>"
}
}
```
**Remediation**: Implement HTML escaping for all user content before rendering.
```
## Legal Considerations
- Only test systems you own or have explicit permission to test
- Comply with computer fraud and abuse laws
- Respect bug bounty program terms
- Obtain written authorization for penetration testing
- Don't disrupt services or access private data
## Continuous Testing
Integrate security testing into CI/CD:
```yaml
# .github/workflows/security-test.yml
name: Security Tests
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run security scan
run: |
cd activitypub-security-poc
npm install
npm run mock-server &
sleep 5
node src/cli.js security-scan --target http://localhost:3000/users/alice/inbox
```