How mobarak93/securesense works
1. Project shape
SecureSense is a Python-based “healthcare IoT security intelligence” agent. The repo is organized around one core agent, a threat-intel MCP service, security analysis utilities, and Terraform deployment assets.
2. Primary runtime entrypoints
The app/ package contains the main agent implementation (agent.py) and the runtime-facing application wrapper (agent_runtime_app.py). These are the central execution path for the agent when it is launched by an agent runtime or orchestration layer.
3. Agent orchestration layer
The agent layer appears to own request handling, prompt/tool coordination, and response assembly. agents-cli-manifest.yaml suggests the project is designed to be packaged or executed through an agent CLI/runtime rather than as a generic library.
4. Threat intelligence service boundary
mcp_server/threat_intel_server.py is a separate MCP server boundary that likely exposes threat-intel capabilities as tools/services to the agent. This separation implies the agent delegates specialized lookups or enrichment to an externalizable tool server instead of embedding all intelligence logic in-process.
5. Security analysis subsystem
The security/ package contains input_validator.py and stride_analyzer.py, which form the main defensive pipeline: validate incoming content first, then analyze it with a STRIDE-oriented security model. security/CONTEXT.md likely documents the security assumptions and threat-modeling context used by that pipeline.
6. Domain/skill logic
skills/real_ids_model.py is the main domain-specific skill module. Based on the name, it likely handles identification or normalization of real-world identifiers in healthcare IoT/security-related inputs, and is a reusable capability the agent can call during analysis.
7. Telemetry and observability
app/app_utils/telemetry.py and the Terraform telemetry assets (deployment/terraform/shared/genai_logs_schema.json, telemetry.tf, telemetry_outputs.tf) indicate a dedicated telemetry/logging path. The architecture includes structured generation/collection of agent logs or GenAI traces, not just application output.
8. Infrastructure as code
deployment/terraform/single-project/ contains the cloud deployment boundary: APIs, IAM, storage, service wiring, and telemetry provisioning. This repo is meant to be deployed as managed infrastructure, with clear separation between application code and cloud resources.
9. Data flow through the system
The likely flow is: input arrives at the agent runtime → input_validator checks it → stride_analyzer classifies risk/threat posture → the agent calls skills and/or the MCP threat-intel server for enrichment → telemetry is emitted for audit/traceability → the response is returned to the caller.
10. Testing and evaluation
The repo has three test layers: unit tests for validator, STRIDE analyzer, skill logic, and threat-intel server; integration tests for the agent and runtime app; and tests/eval/ datasets plus config for repeatable benchmark-style evaluation. This suggests both functional correctness and agent-quality regression testing are first-class concerns.
11. Packaging and execution context
pyproject.toml and uv.lock show a modern Python packaging/runtime setup. The presence of verify_agents.py suggests an additional conformance or validation step for agent artifacts before deployment or release.
12. Architectural boundary summary
For a diagram, the main boxes are: Agent runtime/app, Security layer, Skills/domain logic, MCP threat-intel server, Telemetry/observability, and Terraform-managed cloud infrastructure. The key cross-cutting concern is that all external or high-risk inputs pass through validation and security analysis before the agent consults tools or emits telemetry.
Main entry points: agent.py Agent core · threat_intel_server.py Intel server · telemetry.tf Telemetry stack · agent_runtime_app.py Runtime app
Components 19
Runtime
Agent execution and app-facing entrypoints
- Agent core · Main orchestration and request handling logic
app/agent.py - Runtime app · Runtime-facing wrapper for launching the agent
app/agent_runtime_app.py - Agent manifest · CLI/runtime packaging and execution descriptor
agents-cli-manifest.yaml
Security
Input defense and threat analysis
- Validator · Validates inbound content before analysis
security/input_validator.py - STRIDE · Applies STRIDE-oriented security analysis
security/stride_analyzer.py - Security context · Threat-model and security assumptions for analysis
security/CONTEXT.md
Threat Intel
Externalizable enrichment service boundary
- Intel server · Threat-intel MCP boundary exposed to the agent
mcp_server/threat_intel_server.py
Skills
Domain-specific reusable logic
- ID model · Real-world identifier handling and normalization
skills/real_ids_model.py
Telemetry
Logging and trace emission
- Telemetry · Structured logging and trace emission helpers
app/app_utils/telemetry.py
Infra
Terraform deployment and cloud wiring
- Service stack · Cloud service wiring, APIs, IAM, and storage
deployment/terraform/single-project/service.tf - Telemetry stack · Infrastructure for logs and telemetry provisioning
deployment/terraform/single-project/telemetry.tf - Log schema · Structured schema for GenAI log records
deployment/terraform/shared/genai_logs_schema.json - Completions SQL · Shared completion/query asset used by deployment
deployment/terraform/shared/completions.sql
Tests
Unit, integration, and evaluation coverage
- Eval set · Repeatable evaluation dataset and config
tests/eval/datasets/basic-dataset.json - Eval config · Evaluation harness settings for dataset runs
tests/eval/eval_config.yaml - Agent tests · Integration coverage for agent and runtime app
tests/integration/test_agent.py - Security tests · Unit coverage for validator and STRIDE analysis
tests/unit/test_input_validator.py - Intel tests · Unit coverage for threat-intel server behavior
tests/unit/test_threat_intel_server.py - Verify agents · Validation step for agent artifacts before deployment
verify_agents.py
Connections 20
- Agent manifest → Runtime app: launches · Defines how the agent runtime starts the app
- Runtime app → Agent core: invokes · Wrapper initializes and delegates to core agent
- Agent core → Validator: validates · Inbound content is checked before deeper processing
- Validator → STRIDE: feeds · Validated input is passed into threat analysis
- STRIDE → Security context: guided by · Security assumptions inform the analysis model
- Agent core → ID model: uses · Agent consults domain-specific identifier logic
- Agent core → Intel server: enriches · Agent delegates specialized threat-intel lookups
- Agent core → Telemetry: emits · Operational traces and logs are recorded
- Intel server → Telemetry: logs · MCP service activity contributes to observability
- Service stack → Runtime app: deploys · Cloud service infrastructure hosts the runtime
- Service stack → Intel server: provisions · Deployment includes the external tool/service boundary
- Telemetry stack → Telemetry: provisions · Telemetry infrastructure supports log capture
- Telemetry stack → Log schema: uses · Structured logging schema defines emitted records
- Telemetry stack → Completions SQL: includes · Shared SQL asset supports telemetry/completion plumbing
- Agent tests → Agent core: covers · Integration tests validate the agent flow
- Security tests → Validator: covers · Unit tests verify validation and analysis logic
- Security tests → STRIDE: covers · Unit tests verify STRIDE classification behavior
- Intel tests → Intel server: covers · Unit tests verify MCP threat-intel behavior
- Eval set → Eval config: drives · Dataset is consumed by the evaluation configuration
- Verify agents → Agent manifest: checks · Release validation confirms agent artifact integrity