C‑Sentinel: Semantic Observability for UNIX Systems

# C‑Sentinel: Semantic Observability for UNIX Systems C‑Sentinel is a compact, C‑based probing engine that gathers a holistic view of a Linux host—system metrics, process information, network state, configuration changes, and security events—into a JSON “fingerprint.” The engine’s core advantage lies in its ability to combine traditional observability data with auditd logs to provide a semantic understanding of how and why system states shift, enabling AI‑augmented reasoning that surfaces hidden degradation, causal chains, and context‑rich alerts. --- ## The Observability Gap Modern observability platforms such as Dynatrace, Datadog, and Prometheus excel at collecting metrics and triggering threshold alerts. However, they typically answer a single question: *Is this metric outside its expected range?* They struggle with: * **Causal reasoning** – determining the root cause of an anomaly. * **Context synthesis** – linking a config change weeks ago to a latency spike today. * **Non‑obvious degradation** – catching subtle drifts before full failure. * **Security context** – correlating who accessed what and why it matters. C‑Sentinel addresses these limitations by generating a full system fingerprint that includes security events, then feeding that structured data to a large‑language‑model (LLM) layer that applies semantic reasoning. --- ## Quick‑Start Guide ```sh # Clone the repository git clone https://github.com/williamofai/c-sentinel.git cd c-sentinel # Build the agent (release) make # Perform a one‑shot analysis with network and audit data (requires root for audit logs) sudo ./bin/sentinel --quick --network --audit # Learn baseline patterns (automatic with --audit) ./bin/sentinel --learn --network # Start continuous monitoring (watch mode, 5‑minute intervals) sudo ./bin/sentinel --watch --interval 300 --network --audit ``` #### Command‑Line Overview | Flag | Description | | ---- | ----------- | | `--quick` | Human‑readable summary | | `--network` | Probe listening ports and established connections | | `--audit` | Include security events (requires root) | | `--watch` | Continuous monitoring; specify `--interval` | | `--learn` | Save current state as baseline | | `--json` | Produce a full fingerprint for ingestion | --- ## Architecture Overview ```mermaid flowchart TD A(Web Dashboard) --> B(User Auth & RBAC) A --> C(Email & Slack Notifications) A --> D(Session & Audit Log) B --> E({C‑Sentinel Agent}) E --> F(JSON Fingerprint) F --> G(Dashboard Ingestion API) ``` **C‑Sentinel Agent** (≈99 KB binary) runs on POSIX systems and parses `/proc`, computes SHA‑256 checksums, and optionally reads auditd logs. The lightweight design translates system state into deterministic JSON that can be streamed to the dashboard via HTTP POST. ### Data Capture Categories | Category | Collected Data | Purpose | | -------- | -------------- | ------- | | System | Kernel, uptime, load, memory | Baseline health context | | Processes | Notable process metadata | Zombie/leak detection | | Configs | File metadata & SHA‑256 | Drift & integrity monitoring | | Network | Listeners, connections | Service health | | Security | Auth failures, sudo usage, sensitive file access | Threat detection | --- ## Dashboard Features | Feature | Description | | -------- | ----------- | | **Multi‑User Authentication** | Three roles—Admin, Operator, Viewer—provide granular permissions. | | **Two‑Factor Authentication (TOTP)** | QR‑code setup, supported by Google Authenticator, Authy, etc.; enforced on every login when enabled. | | **Personal API Keys** | Generate per‑user keys (named, expirable) for CI/CD automation; inherit the user’s role permissions. | | **Admin Audit Log** | Records all user actions (login, logout, changes, revocations) with IP, device, and timestamp filters. | | **Session Management** | View, revoke, or force‑logout individual sessions; auto‑cleanup of expired sessions. | | **Security Posture Summary** | Plain‑English verdict on the host’s security health. | | **Explainable Risk Scoring** | Each risk score is broken down into contributing factors and weights. | | **Risk Trend Sparkline** | 24‑hour visual history of risk scores. | | **Email & Slack Alerts** | Proactive notifications for high‑risk thresholds, brute‑force patterns, execution from `/tmp`, etc. | | **Public Demo Mode** | Read‑only viewer access without login; convenient for prospect demos. | --- ## Alerts & Notifications | Trigger | Alert Medium | Notification Content | | ------- | ------------- | --------------------- | | Risk score ≥ 16 | Email / Slack | Structured message with severity, risk factors, and dashboard link | | Brute‑force pattern detected | Email / Slack | Flag and suggested remedial actions | | Execution from `/tmp` or `/dev/shm` | Email / Slack | Suspicious process details | | New IP user login | Email | Account activity summary | Slack integration is enabled via an incoming webhook; the message payload includes coloured severity tags and clickable links to the relevant host view. --- ## Example Output ``` Hostname: axioma-validator Uptime: 14.5 days Load: 0.02 0.04 0.00 Memory: 49.2% used Processes: 120 total Potential Issues: Zombie processes: 0 High FD processes: 1 Long-running (>7d): 95 Config permission issues: 0 Network: Listening ports: 26 Established connections: 14 Unusual ports: 12 ⚠ Security (audit): Auth failures: 6 ⚠ BRUTE FORCE PATTERN DETECTED Sudo commands: 81 Sensitive file access: 2 - /etc/passwd by touch - /etc/shadow by touch ⚠ Risk: high (score: 25) ``` The corresponding JSON payload contains audit summaries, learning state, and detailed risk factors. --- ## Deployment & Automation ### Systemd Service ```sh sudo ./install.sh sudo systemctl enable sentinel sudo systemctl start sentinel sudo journalctl -u sentinel -f ``` ### Scheduler for Continuous Ingestion ```crontab */5 * * * * sudo /usr/local/bin/sentinel --json --network --audit | \ curl -s -X POST \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_KEY" \ -d @- https://your-dashboard.com/api/ingest ``` ### Email / Slack Configuration Configure environment variables in the systemd service or an `env` file: ``` ALERT_EMAIL_ENABLED=true ALERT_SMTP_HOST=smtp.gmail.com ALERT_SMTP_PORT=587 ALERT_SMTP_USER=you@example.com ALERT_SMTP_PASS=app_password ALERT_FROM=you@example.com ALERT_TO=alerts@example.com ALERT_COOLDOWN_MINS=60 ALERT_SLACK_ENABLED=true ALERT_SLACK_WEBHOOK=https://hooks.slack.com/... ALERT_SLACK_CHANNEL=#security-alerts ALERT_SLACK_USERNAME=Sentinel ``` --- ## Privacy Controls * **Username hashing** – failed login usernames are stored as deterministic hashes (e.g., `user_c4c5`) to preserve correlation while protecting identity. * **No command arguments** – sensitive arguments are omitted from logs. * **Process names only** – full executable paths are sanitized. --- ## Roadmap Highlights * Completed: core prober, baseline learning, auditd parsing, risk scoring, web dashboard, multi‑user auth, 2FA, API keys, audit log, email/Slack alerts, public demo mode. * Planned: native FreeBSD/macOS support, Microsoft Teams webhook alerts, custom alert rules, PDF security reports, explicit host‑level permissions. --- ## Licensing & Credits C‑Sentinel is distributed under the MIT License. The project was crafted by William Murray (30 years UNIX engineering experience) and is maintained at GitHub: `@williamofai`. --- > "The goal isn't to replace monitoring tools—it's to add wisdom to their data."