Architecture Overview
This document provides a comprehensive view of Tamandua Sentinel's architecture, including component design, data flow, security model, and on-chain attestation mechanics.
Status note: Windows and Linux are the current public endpoint scope. macOS, mobile, CSPM, Policy Gate, advanced packet NDR, marketplace, and on-chain reputation are roadmap or preview unless a deployment explicitly validates them.
System Architecture
+===========================================================================+
|| TAMANDUA SENTINEL ARCHITECTURE ||
+===========================================================================+
ENDPOINTS TAMANDUA SERVER EXTERNAL
(Customer Controlled) (Customer Controlled) SERVICES
+------------------+ +---------------------------+ +--------------+
| WINDOWS AGENT | | PHOENIX WEB | | SOLANA |
| | | | | DEVNET |
| +------------+ | | +--------------------+ | | |
| | Collectors | | | | LiveView | | | +---------+ |
| | Process | | WSS | | Dashboard | | | | Memo | |
| | File +--+-------->+ +--------------------+ | | | Program | |
| | Network | | | | REST API | | | +---------+ |
| | Registry | | | +--------------------+ | | |
| +------------+ | | | WebSocket | | +--------------+
| | Analyzers | | | | Channels | | ^
| | YARA | | | +--------------------+ | |
| | Entropy | | | | Attestation
| +------------+ | +-------------+------------+ (Privacy-Safe)
| | Response | | | |
| | Kill | | v |
| | Quarantine| | +---------------------------+ |
| | Isolate | | | DETECTION ENGINE |----------+
+------------------+ | |
| +---------------------+ |
+------------------+ | | Broadway | | +--------------+
| LINUX AGENT | | | Pipeline | | | ML SERVICE |
| | | +---------------------+ | | (Python) |
| +------------+ | | | YARA | Sigma | | | |
| | Collectors | | WSS | | Rules | Rules | | | +---------+ |
| | Process +--+-------->+ +---------------------+ | | | Malware | |
| | File | | | | ML Integration +--+--->+ | SMELL | |
| | Network | | | +---------------------+ | | | Model | |
| | Auditd | | | | Alert Manager | | | +---------+ |
| +------------+ | | +---------------------+ | | |
+------------------+ +---------------------------+ +--------------+
|
+------------------+ v
| MACOS AGENT | +---------------------------+
| | | STORAGE |
| +------------+ | | |
| | Collectors | | | +---------------------+ |
| | Process +--+-------->+ | PostgreSQL 16 | |
| | File | | WSS | | + TimescaleDB | |
| | Network | | | +---------------------+ |
| | codesign | | | | Redis | |
| +------------+ | | +---------------------+ |
+------------------+ | | RabbitMQ (optional)| |
| +---------------------+ |
+---------------------------+
The macOS block above represents preview architecture, not a production support claim.
Component Details
Endpoint Agent (Rust)
The agent is a lightweight, cross-platform binary written in Rust for performance and safety.
apps/tamandua_agent/
+-- src/
+-- main.rs # Entry point, collector orchestration
+-- collectors/ # Telemetry collection
| +-- process.rs # Process events (spawn, terminate)
| +-- file.rs # File operations (create, modify, delete)
| +-- network.rs # Network connections
| +-- dns.rs # DNS queries
| +-- registry.rs # Windows registry (Windows only)
| +-- injection.rs # Code injection detection
+-- transport/ # Server communication
| +-- websocket.rs # WebSocket client with reconnect
| +-- auth.rs # JWT and mTLS authentication
+-- response/ # Response actions
| +-- process.rs # Kill processes
| +-- file.rs # Quarantine files
| +-- network.rs # Network isolation
+-- analyzers/ # Local analysis
| +-- yara.rs # YARA rule matching
| +-- entropy.rs # File entropy calculation
| +-- hash.rs # SHA256/MD5 hashing
+-- deception/ # Honeyfile monitoring
+-- honeyfile.rs # Trap file access detection
- Single binary, no runtime dependencies
- Platform-specific collectors using conditional compilation
- Async I/O with Tokio runtime
- Graceful degradation when features unavailable
Server (Elixir/Phoenix)
The server handles agent coordination, telemetry processing, detection, and user interface.
apps/tamandua_server/
+-- lib/
+-- tamandua_server/
| +-- agents/ # Agent registry and lifecycle
| | +-- registry.ex # GenServer tracking online agents
| | +-- worker.ex # Per-agent worker process
| +-- telemetry/ # Event ingestion
| | +-- ingestor.ex # Broadway pipeline
| | +-- enrichment.ex # GeoIP, threat intel enrichment
| +-- detection/ # Detection engine
| | +-- engine.ex # Orchestrates rule matching
| | +-- yara.ex # YARA rule management
| | +-- sigma.ex # Sigma rule parser and matcher
| | +-- ml_client.ex # ML service integration
| +-- response/ # Response orchestration
| | +-- executor.ex # Sends commands to agents
| | +-- playbook.ex # Automated response playbooks
| +-- alerts/ # Alert management
| | +-- alert.ex # Alert schema and lifecycle
| | +-- workflow.ex # Investigation workflows
| +-- solana/ # Blockchain integration
| +-- client.ex # Solana RPC client
| +-- attestation.ex # Privacy-safe attestation builder
+-- tamandua_server_web/
+-- channels/ # WebSocket communication
| +-- agent_channel.ex # Agent protocol
+-- live/ # LiveView dashboards
| +-- dashboard_live.ex
| +-- alerts_live.ex
| +-- investigation_live.ex
+-- controllers/ # REST API
+-- api/v1/
Agent Event --> AgentChannel --> Broadway Pipeline --> Detection Engine
|
v
+--------+--------+
| |
Enrichment Persistence
| |
v v
+-------------------+ PostgreSQL
| YARA | Sigma | ML |
+-------------------+
|
v
Alert Generation
|
v
Attestation (if qualifying)
ML Service (Python)
The ML service provides the Malware-SMELL-inspired scoring path. Current model artifacts are smoke-scale and validation-ready only; production ML claims require the guarded ML-1..ML-6 benchmark chain.
apps/tamandua_ml/
+-- malware_smell/
| +-- model.py # PyTorch model definition
| +-- embeddings.py # Feature embedding layer
| +-- similarity.py # Similarity space computation
+-- training/
| +-- train.py # Training loop
| +-- dataset.py # Data loading
| +-- evaluate.py # Model evaluation
+-- api/
+-- main.py # FastAPI application
+-- endpoints.py # Inference endpoints
+-- schemas.py # Request/response schemas
| Endpoint | Method | Purpose |
|---|---|---|
/health | GET | Health check |
/analyze | POST | Single sample analysis |
/batch | POST | Batch analysis |
/model/info | GET | Model metadata |
Data Flow
Event Lifecycle
+----------+ +----------+ +----------+ +----------+ +----------+
| Endpoint | | Agent | | Server | | Detection| | Alert |
| Activity | | Collect | | Ingest | | Engine | | + Proof |
+----+-----+ +----+-----+ +----+-----+ +----+-----+ +----+-----+
| | | | |
| System call | | | |
+--------------->| | | |
| | TelemetryEvent | | |
| +--------------->| | |
| | | Broadway | |
| | +--------------->| |
| | | | Match rules |
| | | +--------------->|
| | | | ML score |
| | | +--------------->|
| | | | |
| | | | Alert created |
| | | +--------------->|
| | | | |
| | | | Attestation |
| | | | (if med+) |
| | | +--------------->|
+ + + + +
TelemetryEvent Schema
All agent events share a common envelope:
pub struct TelemetryEvent {
pub event_id: Uuid,
pub agent_id: Uuid,
pub timestamp: DateTime<Utc>,
pub event_type: EventType,
pub payload: EventPayload,
pub metadata: EventMetadata,
}
pub enum EventPayload {
Process(ProcessEvent),
File(FileEvent),
Network(NetworkEvent),
Dns(DnsEvent),
Registry(RegistryEvent),
// ...
}
pub struct ProcessEvent {
pub pid: u32,
pub ppid: u32,
pub name: String,
pub path: PathBuf,
pub cmdline: String,
pub user: String,
pub is_elevated: bool,
pub is_signed: Option<bool>,
pub signer: Option<String>,
pub hashes: FileHashes,
}
Security Model
Authentication Layers
+-------------------------------------------------------------------+
| AUTHENTICATION FLOW |
+-------------------------------------------------------------------+
ENROLLMENT RUNTIME
(Initial Setup) (Ongoing)
+-------------+ +-------------+
| Enrollment | | mTLS |
| Token | | Certificate |
+------+------+ +------+------+
| |
v v
+-------------+ +-------------+
| JWT Verify | | CN = Agent |
| + Agent | | ID Verify |
| Registration| +-------------+
+-------------+ |
| |
v v
+-------------------------------------------+
| Agent Session |
| - Org-scoped |
| - Permissions from agent group |
| - Rate limited |
+-------------------------------------------+
JWT Token Structure
{
"agent_id": "uuid",
"org_id": "uuid",
"iat": 1715000000,
"exp": 1715086400,
"capabilities": ["telemetry", "response"],
"enrollment_token_id": "uuid"
}
mTLS Requirements (Production)
| Certificate Field | Requirement |
|---|---|
| Subject CN | Must match agent_id |
| Issuer | Must chain to Tamandua CA |
| Key Usage | Client Authentication |
| Validity | Maximum 1 year |
# Server TLS configuration
config :tamandua_server, TamanduaServerWeb.Endpoint,
https: [
port: 8443,
cipher_suite: :strong,
certfile: "priv/cert/server.pem",
keyfile: "priv/cert/server-key.pem",
cacertfile: "priv/cert/ca.pem",
verify: :verify_peer,
fail_if_no_peer_cert: true
]
Row-Level Security (RLS)
All database queries are scoped by organization:
-- Enable RLS on telemetry_events
ALTER TABLE telemetry_events ENABLE ROW LEVEL SECURITY;
-- Policy: users see only their org's data
CREATE POLICY org_isolation ON telemetry_events
USING (organization_id = current_setting('app.current_org_id')::uuid);
RBAC Model
+-------------------+
| Organization |
+--------+----------+
|
| has_many
v
+--------+----------+ +-------------------+
| Users |---->| Roles |
+-------------------+ +--------+----------+
|
| has_many
v
+--------+----------+
| Permissions |
+-------------------+
| - view_agents |
| - manage_agents |
| - view_alerts |
| - resolve_alerts |
| - execute_response|
| - manage_rules |
| - admin |
+-------------------+
On-Chain Attestation Flow
Privacy Pipeline
When a qualifying alert (medium+ severity) is generated, the attestation pipeline executes:
+------------+ +------------+ +------------+ +------------+
| Alert | | Redact | | Build | | Publish |
| Created | | Sensitive | | Manifest | | to Solana |
+-----+------+ +-----+------+ +-----+------+ +-----+------+
| | | |
v v v v
+----------+ +----------+ +----------+ +----------+
| Severity | | Filter | | Compute | | Memo |
| Check | | PII | | Hashes | | Program |
+----------+ +----------+ +----------+ +----------+
| | | |
| >= medium | No hostname | incident_hash | TX ID
| | No username | manifest_hash |
| | No paths | |
| | No internal IPs | |
| | No cmdline | |
+ + + +
Privacy Guarantees
Sensitive data that is NEVER published:| Data Type | Redaction Method |
|---|---|
| Hostname | Filtered out completely |
| Username | Filtered out completely |
| Internal IP | RFC1918 detection + filter |
| File path | Filtered out completely |
| Command line | Filtered out completely |
| Organization name | SHA256 pseudonym only |
| Agent identifier | SHA256 pseudonym only |
| Field | Example |
|---|---|
| incident_hash | a1b2c3d4... |
| severity | high |
| mitre_technique | T1555.003 |
| ioc_count | 4 |
| ioc_types | ["hash_sha256", "domain"] |
| org_pseudonym | 9f8e7d6c... |
| timestamp | 2026-05-08T12:00:00Z |
Attestation Transaction
+-----------------------------------------------------------+
| SOLANA TRANSACTION |
+-----------------------------------------------------------+
| Program: Memo Program (MemoSq4g...) |
| Signer: Tamandua Server Wallet |
| |
| Memo Data: |
| { |
| "schema": "tamandua.attestation_manifest", |
| "version": 2, |
| "incident_hash": "abc123...", |
| "manifest_hash": "def456...", |
| "severity": "high", |
| "mitre_technique": "T1555.003", |
| "org_pseudonym": "789xyz...", |
| "agent_pseudonym": "012abc...", |
| "timestamp": "2026-05-08T12:00:00Z", |
| "ioc_count": 4, |
| "ioc_types": ["hash_sha256", "domain"], |
| "tlp": "amber", |
| "confidence": 0.91 |
| } |
+-----------------------------------------------------------+
| Transaction ID: 5vErT... |
| Verify: https://solscan.io/tx/5vErT...?cluster=devnet |
+-----------------------------------------------------------+
Attestation Modes
| Mode | Description | Who Pays | Network Contribution |
|---|---|---|---|
relay | Send to Treant relay (default) | Treant | Yes |
local_only | Store locally only | Nobody | No |
self_pay | Use your own Solana wallet | Operator | Yes |
# Configuration
config :tamandua_server, TamanduaServer.Solana.AttestationMode,
mode: :relay,
relay_url: "https://relay.tamandua.treantlab.org/api/v1/attestations"
Detection Engine Architecture
Rule Processing Pipeline
Incoming Event
|
v
+-------------------+
| Event Router |
+--------+----------+
|
+-------------------+-------------------+
| | |
v v v
+----------+ +----------+ +----------+
| YARA | | Sigma | | ML |
| Engine | | Engine | | Client |
+----+-----+ +----+-----+ +----+-----+
| | |
v v v
+----------+ +----------+ +----------+
| 90+ Rules| | 50+ Rules| | Malware |
| Malware | | Behavioral| | SMELL |
+----+-----+ +----+-----+ +----+-----+
| | |
+-------------------+-------------------+
|
v
+-------------------+
| Score Aggregator |
+--------+----------+
|
v
+-------------------+
| Alert Decision |
| (threshold check) |
+--------+----------+
|
v
Alert Created
YARA Integration
// Agent-side YARA scanning
pub fn scan_file(&self, path: &Path) -> Result<Vec<YaraMatch>> {
let rules = self.compiled_rules.lock()?;
let matches = rules.scan_file(path, 60)?; // 60 second timeout
Ok(matches.into_iter().map(|m| YaraMatch {
rule_name: m.identifier.to_string(),
namespace: m.namespace.to_string(),
tags: m.tags.iter().map(|t| t.to_string()).collect(),
meta: m.metadatas.iter()
.map(|m| (m.identifier.to_string(), format_meta_value(&m.value)))
.collect(),
}).collect())
}
Sigma Rule Parser
Full recursive descent parser supporting:
- Logical operators:
AND,OR,NOT - Grouping: Parentheses
- Selection modifiers:
1 of,all of,N of,them - Value modifiers:
contains,startswith,endswith,re,base64,cidr,wide,gt,gte,lt,lte - Aggregations:
count,sum,avg,min,max - Timeframe windowing
# Example Sigma rule matching
defmodule TamanduaServer.Detection.Sigma do
def match_event(event, rule) do
case evaluate_condition(event, rule.detection.condition, rule.detection) do
true -> {:match, rule}
false -> :no_match
end
end
defp evaluate_condition(event, "1 of " <> pattern, detection) do
# Match any one selector matching the pattern
get_matching_selectors(pattern, detection)
|> Enum.any?(fn selector -> evaluate_selector(event, selector) end)
end
end
Scalability Considerations
Horizontal Scaling
Load Balancer
|
+---------------+---------------+
| | |
+----v----+ +----v----+ +----v----+
| Phoenix | | Phoenix | | Phoenix |
| Node 1 | | Node 2 | | Node 3 |
+----+----+ +----+----+ +----+----+
| | |
+---------------+---------------+
|
+----------+----------+
| |
+----v----+ +-----v-----+
| Redis | | PostgreSQL|
| Cluster | | Primary |
+---------+ +-----+-----+
|
+-----+-----+
| Replicas |
+-----------+
Broadway Pipeline Configuration
defmodule TamanduaServer.Telemetry.Ingestor do
use Broadway
def start_link(_opts) do
Broadway.start_link(__MODULE__,
name: __MODULE__,
producer: [
module: {BroadwayRabbitMQ.Producer,
queue: "telemetry_events",
connection: Application.get_env(:tamandua_server, :rabbitmq_url)
},
concurrency: 10
],
processors: [
default: [concurrency: 50, max_demand: 100]
],
batchers: [
default: [concurrency: 10, batch_size: 100, batch_timeout: 200]
]
)
end
end
Deployment Topology
Single Server (Development/Small)
+-------------------------------------------------------+
| Single Server |
| |
| +-------------+ +-------------+ +-------------+ |
| | PostgreSQL | | Redis | | RabbitMQ | |
| +-------------+ +-------------+ +-------------+ |
| |
| +--------------------------------------------------+ |
| | Phoenix Application | |
| | (Web + API + Channels + Detection) | |
| +--------------------------------------------------+ |
| |
| +-------------+ |
| | ML Service | |
| +-------------+ |
+-------------------------------------------------------+
Production (Multi-Server)
Internet
|
+------v------+
| WAF / CDN |
+------+------+
|
+------v------+
| HAProxy |
| (L4/L7) |
+------+------+
|
+-----------------+-----------------+
| | |
+-----v-----+ +-----v-----+ +-----v-----+
| Phoenix 1 | | Phoenix 2 | | Phoenix 3 |
+-----------+ +-----------+ +-----------+
| | |
+-----------------+-----------------+
|
+------------+------------+
| |
+-----v-----+ +-----v-----+
| Redis | | ML |
| Cluster | | Service |
+-----------+ +-----------+
|
+-----v-----+
| PostgreSQL|
| + Patroni |
+-----------+
Integration Points
External Integrations
| Integration | Protocol | Purpose |
|---|---|---|
| Solana | RPC/JSON | Attestation publishing |
| Threat Intel | REST | IOC enrichment |
| SIEM | Syslog/CEF | Alert forwarding |
| Ticketing | Webhooks | Incident creation |
| Slack/Teams | Webhooks | Notifications |
| MDM/UEM | REST | Posture data |
Webhook Events
{
"event_type": "alert.created",
"timestamp": "2026-05-08T12:00:00Z",
"payload": {
"alert_id": "uuid",
"severity": "high",
"mitre_technique": "T1555.003",
"agent_id": "uuid",
"summary": "Credential access detected"
},
"signature": "HMAC-SHA256 signature"
}
Further Reading
- Quick Start Guide - Deploy your first agent
- System Requirements - Hardware and software prerequisites
- Privacy-Safe Attestations - Detailed privacy pipeline documentation
- Detection Rules - Writing YARA and Sigma rules
- Response Playbooks - Automating incident response
Last updated: May 2026