initial commit

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

QUICKSTART.md

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