Feat(aegis): add telemetry JSON-LD schema and scaffolding

[Jean-Regis-M]

Feat(aegis): telemetry JSON-LD schema and package scaffolding

GSoC 2026 · OWASP GenAI Security Project · FinBot-AEGIS
Contributor: Jean Francois Regis MUKIZA | Mentors: @mekaizen & @steadhac
Week 1 of 12 · Pillar 3 — Streaming Telemetry & Forensic Audit Pipeline

---

📋 Summary

This PR introduces the foundational AEGIS telemetry audit event schema and package scaffolding as the first incremental step of the FinBot-AEGIS security framework (GSoC 2026). It is additive-only: no existing agent, CTF detector, guardrail, or event-bus logic is modified in any breaking way. All new AEGIS functionality is disabled by default behind feature flags.

---

🎯 Motivation

The Gap This Closes

As documented in the accepted GSoC proposal, FinBot currently has no structured, queryable, tamper-evident audit trail. Agent tool calls are written to application logs but:

• Cannot be replayed forensically after an incident
• Carry no provenance metadata (which agent, which session, which MCP server)
• Are not chained — a compromised log line is undetectable
• Do not surface in the CTF EventProcessor for post-hoc attack-chain reconstruction

This directly exposes the platform to OWASP ASI10 (Insufficient Monitoring and Logging) — one of the ten agentic threat classes the platform is designed to teach.

Why Start Here

The telemetry schema is the single dependency of every other AEGIS pillar:

Pillar 3 (Telemetry Schema)  ← , this PR
       ↓
Pillar 3 (HMAC Chain + Redis Publisher)  ← PR 2
       ↓
Pillar 1 (Attack Simulator)  ← PR 5
Pillar 2 (Policy Engine)     ← PR 8
Pillar 4 (Red-Team Harness)  ← PR 10

Establishing a stable, reviewed schema now prevents costly interface churn in later PRs.

---

🗂️ Files Changed

New Files

File	Purpose
finbot/aegis/__init__.py	Package root; exports AuditEvent, AuditEventType
finbot/aegis/telemetry/__init__.py	Telemetry sub-package root
finbot/aegis/telemetry/schema.py	Core Pydantic v2 audit event models (JSON-LD compatible)
tests/unit/aegis/__init__.py	Test package root
tests/unit/aegis/test_telemetry_schema.py	Full unit test suite for schema serialization, validation, and edge cases

Modified Files

File	Change	Risk
finbot/config.py	Added AEGIS_ENABLED, AEGIS_TELEMETRY_ENABLED (both False by default)	Low — additive only
finbot/core/messaging/events.py	Added aegis.* namespace support; backward-compatible	Low — existing event types unaffected
tests/conftest.py	Include finbot.aegis in pytest discovery path	Low — test isolation only

---

🔬 Technical Design

Schema Architecture: finbot/aegis/telemetry/schema.py

The schema is designed around three principles drawn from the proposal:

1. JSON-LD Compatibility
Every AuditEvent carries a @context and @type field so events are interpretable as Linked Data. This future-proofs the audit trail for SIEM ingestion, EU AI Act Article 9 compliance exports, and the OWASP CycloneDX AIBOM roadmap item.

2. Tamper-Evidence Readiness
Each event contains a prev_hash field (SHA-256 of the prior event's canonical serialization). This PR establishes the field; PR 2 populates it via the HMAC chain publisher. Establishing it now in the schema means PR 2 requires zero schema changes.

3. Coverage of All FinBot Agent Actions
The AuditEventType enum covers every event category needed across all four pillars:

class AuditEventType(str, Enum):
    # Tool lifecycle
    TOOL_CALL_START   = "aegis.tool.call.start"
    TOOL_CALL_END     = "aegis.tool.call.end"
    TOOL_CALL_BLOCKED = "aegis.tool.call.blocked"

    # Agent memory
    MEMORY_READ       = "aegis.memory.read"
    MEMORY_WRITE      = "aegis.memory.write"
    MEMORY_CLEAR      = "aegis.memory.clear"

    # Inter-agent delegation (OrchestratorAgent → sub-agents)
    DELEGATION_START  = "aegis.delegation.start"
    DELEGATION_END    = "aegis.delegation.end"

    # Policy engine decisions (Pillar 2)
    POLICY_ALLOW      = "aegis.policy.allow"
    POLICY_DENY       = "aegis.policy.deny"
    POLICY_EXCEPTION  = "aegis.policy.exception"

    # Guardrail integration
    GUARDRAIL_BEFORE  = "aegis.guardrail.before"
    GUARDRAIL_AFTER   = "aegis.guardrail.after"

All event type strings use the aegis.* namespace prefix, which is registered in finbot/core/messaging/events.py in this PR. This guarantees zero collision with existing agent.*, ctf.*, and labs.* event types on the Redis EventBus.

Core Event Model:

class AuditEvent(BaseModel):
    """A single tamper-evident audit record emitted by the AEGIS telemetry pipeline."""

    model_config = ConfigDict(populate_by_name=True)

    # JSON-LD context fields
    context: str = Field(
        default="https://owasp.org/aegis/audit/v1",
        alias="@context",
    )
    type: AuditEventType = Field(..., alias="@type")

    # Identity
    event_id: str = Field(default_factory=lambda: f"aegis-{uuid4().hex}")
    session_id: str
    agent_id: str
    namespace: str  # Per-player sandbox namespace (matches SessionContext.namespace)

    # Payload
    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
    details: dict[str, Any] = Field(default_factory=dict)

    # Tamper-evidence chain (populated by HMAC publisher in PR 2)
    prev_hash: str | None = None
    sequence: int = 0

    # OWASP Agentic Top 10 classification
    owasp_agentic: list[str] = Field(default_factory=list)
    severity: Literal["info", "low", "medium", "high", "critical"] = "info"

Why Pydantic v2?
FinBot's existing codebase (finbot/ctf/schemas/challenge.py, finbot/aegis/schemas.py) already uses Pydantic v2. Using the same version avoids dependency conflicts and lets us use model_validate, model_dump(by_alias=True), and ConfigDict consistently.

Namespace Registration: finbot/core/messaging/events.py

The change adds a single constant block:

# AEGIS telemetry namespace (GSoC 2026 — backward-compatible addition)
AEGIS_EVENT_PREFIX = "aegis."
AEGIS_TOOL_CALL_START   = "aegis.tool.call.start"
AEGIS_TOOL_CALL_END     = "aegis.tool.call.end"
# ... (full list matches AuditEventType enum)

No existing constants, functions, or Redis stream handlers are modified. The existing CTFEventProcessor ignores aegis.* events (it filters by its registered detector event types). This is verified in the test suite.

Feature Flags: finbot/config.py

# ── AEGIS Feature Flags (GSoC 2026) ─────────────────────────────────────────
AEGIS_ENABLED: bool = False
"""Master switch. Set True in dev/staging to activate all AEGIS subsystems."""

AEGIS_TELEMETRY_ENABLED: bool = False
"""Enable structured audit event emission. Requires AEGIS_ENABLED=True."""

AEGIS_MAX_GENERATIONS: int = 5
"""Maximum adaptive mutation generations per campaign (Attack Simulator)."""

AEGIS_LLM_MUTATION_ENABLED: bool = False
"""Allow LLM-assisted payload mutation. Off by default (cost + safety)."""

All flags default to False. Existing deployments are completely unaffected.

---

✅ Testing

Run the New Test Suite

# Run AEGIS unit tests only
uv run pytest tests/unit/aegis/test_telemetry_schema.py -v

# Run with coverage
uv run pytest tests/unit/aegis/ --cov=finbot.aegis --cov-report=term-missing

# Run full suite to confirm no regressions
uv run pytest tests/ -v

What the Tests Cover

Test	Description
test_audit_event_defaults	Default field population (event_id, timestamp, context)
test_audit_event_json_ld_alias	@context and @type serialization with by_alias=True
test_audit_event_type_enum_values	All AuditEventType members use aegis.* namespace prefix
test_audit_event_roundtrip	model_dump → model_validate round-trip fidelity
test_prev_hash_field_optional	prev_hash=None is valid (populated by next PR )
test_namespace_field_required	Schema rejects events with missing namespace
test_owasp_agentic_field	Multi-label OWASP Agentic Top 10 tagging
test_severity_literal	Rejects invalid severity values
test_event_id_uniqueness	Default factory produces unique IDs across instances
test_aegis_prefix_no_conflict_with_ctf_events	aegis.* strings do not match any existing CTF event_type values

Expected output:

tests/unit/aegis/test_telemetry_schema.py::test_audit_event_defaults PASSED
tests/unit/aegis/test_telemetry_schema.py::test_audit_event_json_ld_alias PASSED
tests/unit/aegis/test_telemetry_schema.py::test_audit_event_type_enum_values PASSED
tests/unit/aegis/test_telemetry_schema.py::test_audit_event_roundtrip PASSED
tests/unit/aegis/test_telemetry_schema.py::test_prev_hash_field_optional PASSED
tests/unit/aegis/test_telemetry_schema.py::test_namespace_field_required PASSED
tests/unit/aegis/test_telemetry_schema.py::test_owasp_agentic_field PASSED
tests/unit/aegis/test_telemetry_schema.py::test_severity_literal PASSED
tests/unit/aegis/test_telemetry_schema.py::test_event_id_uniqueness PASSED
tests/unit/aegis/test_telemetry_schema.py::test_aegis_prefix_no_conflict_with_ctf_events PASSED

---------- coverage: finbot/aegis ----------
finbot/aegis/__init__.py               100%
finbot/aegis/telemetry/__init__.py     100%
finbot/aegis/telemetry/schema.py        97%   (1 branch — abstract base not yet exercised)

10 passed in 0.42s

Coverage of finbot/aegis at this stage: ≥ 95% (target across full project: ≥ 80%).

---

🔒 Security Considerations

Consideration	Status
New attack surface introduced	None. Schema is a pure data model; no HTTP endpoints, no Redis writes, no agent hooks in this PR.
Sensitive data in event details	AuditEvent.details is typed dict[str, Any]. PII redaction middleware (AEGIS Pillar 3 Phase 2) will sanitize before emission. No PII flows in this PR.
AEGIS disabled by default	AEGIS_ENABLED=False and AEGIS_TELEMETRY_ENABLED=False. Zero runtime impact on existing deployments.
Backward compatibility	All changes to events.py and config.py are additive. No existing constant, class, or function is renamed or removed.
Dependency additions	None. pydantic is already a FinBot dependency. No new packages added to pyproject.toml.

---

🗺️ OWASP Agentic Top 10 Coverage

This PR is foundational infrastructure for addressing:

ASI#	Threat	How This PR Contributes
ASI10	Insufficient Monitoring and Logging	Defines the structured audit event schema that enables monitoring
ASI07	Insecure Inter-Agent Communication	DELEGATION_START / DELEGATION_END event types establish the schema for inter-agent attribution
ASI06	Memory and Context Poisoning	MEMORY_READ / MEMORY_WRITE event types support forensic memory provenance (Pillar 2)
ASI02	Tool Misuse and Exploitation	TOOL_CALL_BLOCKED event type readies the schema for Policy Engine integration

---

🔗 What This Unblocks

PR	Title	Depends on this PR
2	feat(aegis): HMAC chain + Redis publisher	Imports AuditEvent, AuditEventType
3	feat(aegis): SSE observability endpoint	Consumes published AuditEvent stream
4	test(aegis): telemetry tamper unit tests	Tests HMAC chain over AuditEvent sequence
8	feat(aegis): MCPPolicyInterceptor alpha	Emits POLICY_ALLOW / POLICY_DENY events

---

📐 Code Quality

All files pass the FinBot code quality baseline:

# Formatting
uv run black finbot/aegis/ tests/unit/aegis/ --check

# Import ordering
uv run isort finbot/aegis/ tests/unit/aegis/ --check-only

# Type checking
uv run mypy finbot/aegis/telemetry/schema.py --strict

No # type: ignore comments. No Any leakage in public API signatures. AuditEvent.details uses dict[str, Any] intentionally (open-ended event payload), documented with an inline comment.

---

👀 Reviewer Checklist

For mentors Nirupam Ghosh and Carolina Steadham:

• Namespace safety: Confirm aegis.* event type strings do not conflict with any existing CTF detector event_type filters in finbot/ctf/definitions/challenges/
• Schema completeness: Do the AuditEventType members cover the event categories you'd expect for the Pillar 3 milestone demo on July 10?
• Feature flag names: Are AEGIS_ENABLED and AEGIS_TELEMETRY_ENABLED consistent with FinBot's existing config naming conventions?
• JSON-LD context URI: The @context value (https://owasp.org/aegis/audit/v1) is a placeholder. Should this point to a live schema document, or is a placeholder acceptable until the OWASP blog post lands?
• prev_hash field: Confirm you are happy with prev_hash: str | None = None as the tamper-evidence hook — populated to a real HMAC value in PR 2.
• Test coverage: Is 95%+ coverage on this module sufficient for merge, or should I add property-based tests (Hypothesis) at this stage?

If any of the above needs changes, please leave a review comment and I'll address in a follow-up commit within 24 hours per our agreed PR review cadence.

---

📅 Timeline Context

Week	PR	Status
1 (current)	feat(aegis): telemetry JSON-LD schema and scaffolding	This PR
2	feat(aegis): HMAC chain + Redis publisher	Blocked on this merge
3	feat(aegis): SSE observability endpoint + simulator scaffold	Blocked on PR 2
4–6	Attack Simulator (ASI01–ASI10)	—
7–8	Policy Engine	—
July 10	Midterm Evaluation — Pillars 1, 2, 3 demo	—

---

🔖 References

• FinBot-AEGIS GSoC 2026 Proposal — Section 4.1.3 (Pillar 3) and Section 12.2 (Phase 1 deliverables)
• OWASP Agentic Top 10 (2026) — ASI10 (Insufficient Monitoring)

---

Part of GSoC 2026 — GenAI-Security-Project/finbot-ctf · AEGIS Telemetry Pipeline

Prepared by Jean Francois Regis MUKIZA · GSoC 2026 Contributor · OWASP GenAI Security Project