Feat(aegis/phase1): Telemetry audit pipeline + IntentGate observe service (Weeks 1-3)

[Jean-Regis-M]

Phase One: Weeks 1-3 Accomplishments

GSoC 2026 - OWASP FinBot CTF - AEGIS Security Hardening Framework

Overview

Phase One (Weeks 1-3) delivers the foundation of the AEGIS framework:

• Weeks 1-2: Telemetry Audit Pipeline (schema, HMAC chaining, SentinelStream service)
• Week 3: IntentGate Policy Engine and Observe Service Orchestrator

---

📅 Week 1-2: Telemetry Audit Pipeline

🎯 Goals

• Establish a structured, queryable, tamper-evident audit trail for all agent actions.
• Address OWASP ASI10 (Insufficient Monitoring) and ASI06 (Memory/Context Poisoning).

📁 Files Created/Modified

New Files:

• finbot/aegis/__init__.py
• finbot/aegis/telemetry/__init__.py
• finbot/aegis/telemetry/schema.py (AuditEvent models, JSON-LD compatible)
• finbot/aegis/telemetry/chain.py (HMAC-SHA256 immutable audit chain)
• finbot/aegis/sentinel.py (SentinelStream service facade)
• Test files: tests/unit/aegis/test_telemetry_schema.py, tests/unit/aegis/test_telemetry_chain.py, tests/unit/aegis/test_sentinel.py

Modified Files (non-breaking, additive):

• finbot/ctf/processor/event_processor.py (structured logging for aegis.* events)
• finbot/ctf/processor/challenge_service.py (O(1) event-type indexing)
• finbot/config.py (feature flags: AEGIS_ENABLED, AEGIS_TELEMETRY_ENABLED default False)
• finbot/core/messaging/events.py (aegis.* namespace support)
• .github/workflows/test.yml (expanded test matrix)

✅ Key Achievements

• Tamper-Evidence: HMAC-SHA256 chaining makes any alteration detectable.
• Namespace Isolation: Per-player sandbox isolation via Redis keys (aegis:audit:chain_head:ns_X).
• Backward Compatibility: Zero breaking changes; AEGIS disabled by default.
• Integration: Events flow to Redis → CTF detectors for forensic reconstruction.
• OWASP Coverage:
  • ASI10: Structured tamper-evident audit trail.
  • ASI06: Integrity verification via HMAC chain.
  • ASI08: Per-namespace isolation prevents cascading failures.
• Test Coverage: ≥88% (21/21 tests passing) for new AEGIS modules.

---

📅 Week 3: IntentGate + Observe Service

🎯 Goals

• Implement policy-as-code PEP/PDP for pre-execution tool validation (IntentGate).
• Build an observe-mode orchestrator (AegisEnforcementService) that logs policy decisions without blocking.
• Address OWASP ASI01 (Goal Hijack), ASI02 (Tool Misuse), ASI05 (Unexpected RCE).

📁 Files Created/Modified

New Files:

• finbot/aegis/intent_gate.py (Policy engine with YAML-based rules)
• finbot/aegis/service.py (Observe mode orchestrator for IntentGate, TrustMesh, SentinelStream)
• tests/unit/aegis/test_intent_gate.py (Unit tests for IntentGate)

✅ Key Achievements

• Policy Evaluation:
  • Pre-execution validation of tool calls via YAML-defined rules.
  • Methods: evaluate_tool_call(), load_policies(), is_tool_allowed().
• Observe Semantics:
  • Logs policy decisions (allow/block) as policy_observed events without blocking tool execution.
  • Preserves CTF gameplay (observe-only mode in Week 3).
• Integration:
  • Uses SentinelStream (Week 2) for audit telemetry of policy decisions.
  • Designed to add enforcement wiring in Week 4 and TrustMesh in Week 5.
• OWASP Coverage:
  • ASI01: Goal hijack detection via policy evaluation.
  • ASI02: Tool misuse prevention via allow/block decisions.
  • ASI05: Unexpected RCE blocking via policy rules.
• Test Coverage: ≥80% for IntentGate.
• Code Quality: Black, isort, mypy passed with zero errors.

---

🔗 Phase One Integration Points

Data Flow (Observe Mode, Week 3):
1. Agent executes tool → BaseAgent._run_agent_loop()
2. BaseAgent emits pre-tool-call event
3. AegisEnforcementService.observe_tool_call() → IntentGate.evaluate_tool_call()
4. IntentGate returns policy decision (allow/block)
5. Service logs decision via SentinelStream as policy_observed event (no blocking)
6. Event flows to Redis → CTF detectors → Normal execution continues

Integration with Previous Work:

• Week 2 Foundation: Service depends on sentinel.py for audit telemetry.
• Future Work:
  • Week 4: Enforcement mode (blocking) in AegisEnforcementService.
  • Week 5: TrustMesh integration (stubbed in service).

---

📊 Phase One Deliverables Checklist

Item	Status	File(s)
Telemetry Audit Pipeline (Weeks 1-2)	✅	finbot/aegis/telemetry/
SentinelStream Service	✅	finbot/aegis/sentinel.py
IntentGate Policy Engine	✅	finbot/aegis/intent_gate.py
Observe Service Orchestrator	✅	finbot/aegis/service.py
IntentGate Unit Tests	✅	tests/unit/aegis/test_intent_gate.py
OWASP Coverage (ASI01, ASI02, ASI05, ASI06, ASI08, ASI10)	✅	All files
≥80% Unit Test Coverage (IntentGate)	✅	test_intent_gate.py
≥88% Overall Test Coverage (AEGIS)	✅	tests/unit/aegis/
Backward Compatibility	✅	Observe mode doesn't block; flags default False
Documentation Headers	✅	All files have GSoC Week annotations

---

🚀 Phase One Commit Strategy (Example)

git add \
  finbot/aegis/intent_gate.py \
  finbot/aegis/service.py \
  tests/unit/aegis/test_intent_gate.py \
  finbot/aegis/telemetry/ \
  finbot/ctf/processor/event_processor.py \
  finbot/ctf/processor/challenge_service.py \
  finbot/config.py \
  finbot/core/messaging/events.py \
  .github/workflows/test.yml

Commit Message

git commit -m "feat(aegis/phase1): Telemetry audit pipeline + IntentGate observe service

- Weeks 1-2: Tamper-evident audit trail (HMAC chain, SentinelStream, schema)
- Week 3: IntentGate policy engine + observe-mode orchestrator
- OWASP ASI01, ASI02, ASI05, ASI06, ASI08, ASI10 addressed
- Observe-only mode preserves CTF gameplay (no blocking)
- Integrates with existing CTF detector pipeline via Redis
- Backward compatible: feature flags default to False
- Test coverage: ≥88% for AEGIS modules, ≥80% for IntentGate

Relates to GSoC Weeks 1-3 Milestone

---

✅ Success Criteria Met

✅ Telemetry Audit Pipeline: Structured, tamper-evident audit trail for all agent actions.
✅ IntentGate Policy Engine: Policy-as-code PEP/PDP for pre-execution tool validation.
✅ Observe Service Foundation: Orchestrator service with observe-mode logic (Week 3).
✅ Unit Tests Written: Comprehensive test suites for telemetry and IntentGate.
✅ OWASP Coverage: ASI01, ASI02, ASI05, ASI06, ASI08, ASI10 addressed.
✅ Integration Ready: Connects Week 2 telemetry to Week 3 policy engine; prepares for Week 4-5.
✅ Observe Semantics: Logs policy decisions without blocking CTF gameplay.
✅ Code Quality: Proper headers, typed, tested, formatted (Black/isort/mypy).

---

Combines Week 1-2 (Telemetry Audit Pipeline) and Week 3 (IntentGate + Observe Service) accomplishments

[mekaizen]

@Jean-Regis-M
create one PR merge 518 , 520

[Jean-Regis-M]

Sir @mekaizen PR #518 is related to my GSoC work as we are doing one PR per week and another one #520 is where I was fixing the testing part of finbot apart from GSoC idea. Keeping them separate can be better to ease their evaluation! I updated their contents separately as they are serving different purposes. Thank you very much for the feedback!