activitypub-security-poc/examples/USAGE.md

# ActivityPub Security PoC - Usage Examples

## Quick Start

### 1. Install Dependencies

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

### 2. Start the Mock Server

In one terminal:

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

Or using npm script:

```bash
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:

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

## Command Reference

### Fetch Actor Profile

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

### Test Outbox Endpoint

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

### Send Activity to Inbox

Using a predefined payload:

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

Using inline content:

```bash
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:

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

Run specific tests:

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

Save results to file:

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

### Craft Custom Activities

Create a simple note:

```bash
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:

```bash
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

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
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:

```bash
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**:
   ```bash
   npm run mock-server
   ```

2. **Test basic connectivity**:
   ```bash
   node src/cli.js fetch-actor --target http://localhost:3000/users/alice
   ```

3. **Send test activity**:
   ```bash
   node src/cli.js test-inbox \
     --target http://localhost:3000/users/alice/inbox \
     --content "Testing basic delivery"
   ```

4. **Run security tests**:
   ```bash
   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:

```json
{
  "@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:

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

### Testing Different Activity Types

```bash
# 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

```json
{
  "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