activitypub-security-poc/examples/USAGE.md

ActivityPub Security PoC - Usage Examples

Quick Start

1. Install Dependencies

cd activitypub-security-poc
npm install

2. Start the Mock Server

In one terminal:

node src/cli.js mock-server --port 3000

Or using npm script:

npm run mock-server

The mock server will start at http://localhost:3000 with two test users: alice and bob.

3. Test the Mock Server

In another terminal, try fetching an actor profile:

node src/cli.js fetch-actor --target http://localhost:3000/users/alice

Command Reference

Fetch Actor Profile

node src/cli.js fetch-actor --target https://mastodon.social/@username

Test Outbox Endpoint

node src/cli.js test-outbox --target http://localhost:3000/users/alice/outbox

Send Activity to Inbox

Using a predefined payload:

node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --payload examples/create-note.json

Using inline content:

node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --content "Hello from security PoC!" \
  --actor https://example.com/users/tester

Run Security Scans

Run all security tests:

node src/cli.js security-scan \
  --target http://localhost:3000/users/alice/inbox \
  --actor http://localhost:3000/users/alice

Run specific tests:

node src/cli.js security-scan \
  --target http://localhost:3000/users/alice/inbox \
  --tests xss,ssrf

Save results to file:

node src/cli.js security-scan \
  --target http://localhost:3000/users/alice/inbox \
  --output results.json

Craft Custom Activities

Create a simple note:

node src/cli.js craft \
  --type Create \
  --object Note \
  --content "Custom activity message" \
  --actor https://example.com/users/tester \
  --to https://www.w3.org/ns/activitystreams#Public

Save to file:

node src/cli.js craft \
  --type Follow \
  --object https://target.example/users/alice \
  --actor https://example.com/users/tester \
  --output examples/my-follow.json

Testing Against Real Instances

⚠️ Warning: Always obtain permission before testing third-party systems!

Testing Mastodon

# Fetch actor
node src/cli.js fetch-actor --target https://mastodon.social/@Gargron

# Fetch outbox
node src/cli.js test-outbox --target https://mastodon.social/@Gargron/outbox

Testing Your Own Instance

If you're running your own Mastodon instance:

# Security scan on your instance
node src/cli.js security-scan \
  --target https://your-instance.example/users/yourusername/inbox \
  --tests xss,injection \
  --output my-instance-scan.json

Security Test Scenarios

1. XSS Testing

Test for Cross-Site Scripting vulnerabilities:

node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --payload examples/xss-payload.json

The mock server will detect and log XSS patterns.

2. SSRF Testing

Test for Server-Side Request Forgery:

node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --payload examples/ssrf-payload.json

3. Full Security Audit

Run comprehensive tests:

node src/cli.js security-scan \
  --target http://localhost:3000/users/alice/inbox \
  --tests all \
  --output full-audit-$(date +%Y%m%d).json

Testing Workflow

Complete Testing Session

1. Start mock server:

   npm run mock-server
   

2. Test basic connectivity:

   node src/cli.js fetch-actor --target http://localhost:3000/users/alice
   

3. Send test activity:

   node src/cli.js test-inbox \
     --target http://localhost:3000/users/alice/inbox \
     --content "Testing basic delivery"
   

4. Run security tests:

   node src/cli.js security-scan \
     --target http://localhost:3000/users/alice/inbox
   

5. Review mock server logs for detected issues

Advanced Usage

Custom Security Tests

You can create custom payloads by editing the JSON files in examples/ or creating new ones:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "actor": "https://example.com/users/tester",
  "object": {
    "type": "Note",
    "content": "Your custom test content"
  }
}

Then test it:

node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --payload your-custom-payload.json

Testing Different Activity Types

# Follow activity
node src/cli.js craft --type Follow --object https://target.example/users/alice | \
  node src/cli.js test-inbox --target http://localhost:3000/users/bob/inbox --payload -

# Update activity
node src/cli.js craft --type Update --content "Updated content"

# Delete activity
node src/cli.js craft --type Delete --object https://example.com/notes/123

Interpreting Results

Mock Server Output

The mock server will display:

• 📥 Received activities
• ⚠️ Validation warnings
• 🚨 Security issues detected

Security Scan Output

• ✅ SAFE - The endpoint properly handled the test
• ❌ VULNERABLE - Potential security issue detected

Result JSON Structure

{
  "target": "http://localhost:3000/users/alice/inbox",
  "timestamp": "2025-11-16T...",
  "tests": {
    "xss": [...],
    "ssrf": [...],
    "injection": [...]
  }
}

Best Practices

1. Always test on your own infrastructure first
2. Get explicit permission before testing external systems
3. Review logs on both client and server side
4. Document your findings
5. Report vulnerabilities responsibly

Troubleshooting

Connection Refused

• Ensure the target server is running
• Check firewall rules
• Verify the URL is correct

401/403 Errors

• The endpoint requires authentication
• HTTP signatures may be required
• Check if the endpoint accepts external activities

Timeout Errors

• Server may be slow or unreachable
• Increase timeout with client configuration
• Check network connectivity

Next Steps

• Review the source code in src/ to understand how tests work
• Modify security-tester.js to add custom tests
• Extend mock-server.js with more realistic behavior
• Integrate with your CI/CD pipeline for automated testing