activitypub-security-poc/QUICKSTART.md

# ActivityPub Security PoC - Quick Reference

## Installation

```bash
cd activitypub-security-poc
npm install
```

## Quick Commands

### Start Mock Server
```bash
npm run mock-server
# or
node src/cli.js mock-server --port 3000
```

### Run Quick Test
```bash
./test.sh
```

### Fetch Actor
```bash
node src/cli.js fetch-actor --target http://localhost:3000/users/alice
```

### Test Inbox
```bash
node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --content "Test message"
```

### Security Scan
```bash
node src/cli.js security-scan \
  --target http://localhost:3000/users/alice/inbox
```

### Craft Activity
```bash
node src/cli.js craft --type Create --object Note --content "Hello"
```

## Common Use Cases

### Test Local Mastodon Instance
```bash
# Start mock server
npm run mock-server

# In another terminal, send activity
node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --payload examples/create-note.json
```

### Test XSS Vulnerability
```bash
node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --payload examples/xss-payload.json
```

### Test SSRF Vulnerability
```bash
node src/cli.js test-inbox \
  --target http://localhost:3000/users/alice/inbox \
  --payload examples/ssrf-payload.json
```

### Full Security Audit
```bash
node src/cli.js security-scan \
  --target http://localhost:3000/users/alice/inbox \
  --output results-$(date +%Y%m%d).json
```

## Testing Against Real Instances

⚠️ **Get permission first!**

```bash
# Fetch public data (usually allowed)
node src/cli.js fetch-actor --target https://mastodon.social/@Gargron
node src/cli.js test-outbox --target https://mastodon.social/@Gargron/outbox

# Testing inbox requires authorization
node src/cli.js test-inbox \
  --target https://your-instance.example/users/you/inbox \
  --content "Test from security PoC"
```

## File Structure

```
activitypub-security-poc/
├── src/
│   ├── cli.js                 # Main CLI
│   ├── activitypub-client.js  # HTTP client
│   ├── security-tester.js     # Security tests
│   └── mock-server.js         # Mock server
├── examples/
│   ├── *.json                 # Sample payloads
│   └── USAGE.md              # Detailed usage
└── docs/
    ├── ARCHITECTURE.md        # Architecture docs
    └── SECURITY_TESTING.md    # Testing guide
```

## Help Commands

```bash
# Main help
node src/cli.js --help

# Command-specific help
node src/cli.js test-inbox --help
node src/cli.js security-scan --help
```

## Tips

- Use `--output` to save results to JSON
- Use `--tests` to run specific security tests
- Check mock server logs for detected vulnerabilities
- Read USAGE.md and SECURITY_TESTING.md for details
- Always test with permission

## Example Workflow

```bash
# Terminal 1: Start mock server
npm run mock-server

# Terminal 2: Run tests
node src/cli.js fetch-actor --target http://localhost:3000/users/alice
node src/cli.js test-inbox --target http://localhost:3000/users/alice/inbox --content "Hello"
node src/cli.js security-scan --target http://localhost:3000/users/alice/inbox

# Check Terminal 1 for server logs showing received activities and security issues
```

## Troubleshooting

**"Cannot find module"**: Run `npm install`

**"ECONNREFUSED"**: Start the mock server first

**"Command not found"**: Use `node src/cli.js` instead of just `cli.js`

**Timeout errors**: Check if target is reachable

## Security Reminder

This tool is for **authorized security testing only**. Use it to:
- Test your own servers
- Conduct authorized penetration tests
- Learn about ActivityPub security
- Develop secure implementations

Do NOT use it to:
- Attack systems without permission
- Exploit vulnerabilities
- Disrupt services
- Access unauthorized data