activitypub-security-poc/docs/ARCHITECTURE.md

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:

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:

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:

// 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:

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():

if (!options.tests || options.tests.includes('newvuln')) {
  allResults.tests.newVuln = await this.testNewVulnerability(targetUrl);
}

Adding New CLI Commands

1. Add command to cli.js:

program
  .command('new-command')
  .description('Description')
  .option('-f, --flag <value>', 'Option')
  .action(async (options) => {
    // Implementation
  });

Extending Mock Server

1. Add new endpoint handler:

async handleNewEndpoint(req, res, path) {
  // Handle request
  this.sendJSON(res, data);
}

2. Add route in handleRequest():

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