A2_START_HERE.md

🚀 PHASE 5 A2: STARTING NOW

Status: 🟢 READY TO IMPLEMENT Date: November 3, 2025 Task: A2 - Rate Limiting Verification Duration: 3-4 hours Target: November 6, 2025

---

📌 Executive Summary

Next Task: Implement @rate_limit decorator to protect all API endpoints Objective: Prevent brute force attacks with per-IP rate limiting (50 req/hr for commands) Deliverables:

• RateLimitManager + decorator integrated
• All vulnerable endpoints protected
• Unit tests + brute force tests passing
• Performance verified < 50ms overhead

---

🎯 Quick Start (5 min read)

What You're Building

A token bucket rate limiter that:

• Tracks requests per client IP
• Allows 50 requests/hour for sensitive endpoints
• Returns HTTP 429 when limit exceeded
• Has negligible performance impact

Where to Get Code

File: SECURITY_DECORATORS_IMPLEMENTATION_GUIDE.md

• Section: "Decorator 1: @rate_limit"
• Contains complete RateLimitManager class (~80 lines)
• Contains @rate_limit decorator (~60 lines)
• Contains 35+ usage examples

Implementation Steps (4 steps total)

1. Copy RateLimitManager class to api_server.py
2. Copy @rate_limit decorator function
3. Apply @rate_limit(calls=50, period=3600) to endpoints
4. Run tests to verify

---

📁 Reference Files

📄 SECURITY_DECORATORS_IMPLEMENTATION_GUIDE.md
   ├─ RateLimitManager class (copy this)
   ├─ @rate_limit decorator (copy this)
   ├─ 35+ usage examples (reference for syntax)
   └─ Unit test examples (reference for testing)

📄 A2_RATE_LIMITING_IMPLEMENTATION.md
   ├─ Complete step-by-step guide
   ├─ Code placement instructions
   ├─ Test strategy
   └─ Troubleshooting guide

📄 A2_SESSION_TRACKING.md
   ├─ Live session progress
   ├─ Detailed implementation roadmap
   ├─ Test results tracking
   └─ Performance metrics

📄 SECURITY_AUDIT_A1_DECORATOR_AUDIT.md
   └─ Audit report (reference for why rate limiting needed)

📄 api_server.py
   └─ Target file (where to add the code)

---

⏱️ Timeline Estimate

Phase	Task	Time	Status
1	Add imports & copy classes	30 min	⏳ START
2	Apply decorators to endpoints	30 min	⏳ NEXT
3	Create & run tests	60 min	⏳ THEN
4	Documentation & config	30 min	⏳ FINALLY
	TOTAL	150 min

---

🎬 Begin Implementation

Phase 1: Integration (30 min)

What: Add imports and copy two classes from implementation guide

Steps:

1. Open api_server.py (around line 1-10)
2. Add: from threading import Lock, RLock
3. Add: from time import time
4. Add: from collections import defaultdict
5. Open SECURITY_DECORATORS_IMPLEMENTATION_GUIDE.md
6. Find section: "RateLimitManager Implementation"
7. Copy complete class (~80 lines)
8. Paste into api_server.py after AGENT_INSTANCE global (line 13)
9. Find section: "Decorator 1: @rate_limit Implementation"
10. Copy decorator function (~60 lines)
11. Paste after RateLimitManager class (~line 100)
12. Add: RATE_LIMITER = RateLimitManager() after decorator

Verification:

python -m py_compile c:\Projects\ultron_agent\api_server.py
echo "✅ No syntax errors"

---

Phase 2: Endpoint Protection (30 min)

What: Add decorator to all vulnerable endpoints

Steps:

1. Find /command route in api_server.py (~line 180)
2. Add line: @rate_limit(calls=50, period=3600)
3. Find other POST/PUT/DELETE routes with grep:

   Select-String -Path c:\Projects\ultron_agent\api_server.py -Pattern '@app.route.*POST|PUT|DELETE'

4. Add rate limit decorator to each (examples: /api/tools/execute, /api/model/switch)
5. DELETE routes: @rate_limit(calls=20, period=3600)
6. Verify syntax again

---

Phase 3: Testing (60 min)

What: Create unit tests + brute force tests

Steps:

1. Create: tests/test_rate_limiter.py
2. Copy test examples from SECURITY_DECORATORS_IMPLEMENTATION_GUIDE.md
3. Run: pytest tests/test_rate_limiter.py -v
4. All tests should PASS ✅
5. Create: tests/test_brute_force.py
6. Run 100 concurrent requests to /command
7. Verify: ~50 succeed (200), ~50 blocked (429)
8. Measure latency: should be < 50ms average

---

Phase 4: Documentation (30 min)

What: Configure and document

Steps:

1. Update ultron_config.json with rate limit settings
2. Add comments to api_server.py explaining limits
3. Update README.md with rate limiting section
4. Document in code: why each endpoint has its limit

---

✅ Success Criteria

When A2 is complete, you should have:

• RateLimitManager class in api_server.py
• @rate_limit decorator in api_server.py
• Decorator applied to /command endpoint
• Decorator applied to all POST/PUT/DELETE endpoints
• Unit tests: 100% pass (all 4+ tests)
• Brute force test: 50+ requests blocked
• Performance: < 50ms average overhead
• Configuration documented in ultron_config.json
• Code comments explaining rate limits
• README.md updated with rate limiting info

Total Expected: ~3-4 hours to complete

---

🚀 Start Now

Immediate Next Action

Open this file in order:

1. SECURITY_DECORATORS_IMPLEMENTATION_GUIDE.md (get the code)
2. api_server.py (paste the code)
3. A2_RATE_LIMITING_IMPLEMENTATION.md (reference while implementing)

Copy-paste code locations are clearly marked in all reference files.

Estimated time to first working version: 45 minutes

---

📞 Need Help?

Question	Answer Location
"Where's the code to copy?"	SECURITY_DECORATORS_IMPLEMENTATION_GUIDE.md → Decorator 1
"How do I apply the decorator?"	A2_RATE_LIMITING_IMPLEMENTATION.md → Step-by-Step Guide
"What tests do I run?"	A2_SESSION_TRACKING.md → Step 9-10
"Why rate limiting?"	SECURITY_AUDIT_A1_DECORATOR_AUDIT.md → @rate_limit section
"How to configure?"	A2_RATE_LIMITING_IMPLEMENTATION.md → Configuration Template

---

📊 Current Project Status

Phase 5 Progress: 35% → 37% (after A2)
├─ ✅ A1: Security Decorator Audit (COMPLETE)
├─ 🔴 A2: Rate Limiting (STARTING NOW)
├─ ⏳ A3: Input Validation (Nov 6-8)
├─ ⏳ A4: CORS & Headers (Nov 10-12)
├─ ⏳ A5-A6: Documentation (Nov 13-15)
└─ ⏳ C1-C6: Copilot Integration (Nov 16-17)

Target Completion: November 17, 2025 ✅ ON TRACK

---

Ready? Start with SECURITY_DECORATORS_IMPLEMENTATION_GUIDE.md and begin copying code! 🚀

This should take 3-4 hours total. Estimated completion by end of day November 5 or morning November 6.