Sentora

KO | EN

gitlite — search

#golang #go #nextjs #terminal #developer-tools #automation #mcp #github #csharp #command-line

(★ 9)

An open-source, self-hosted AI-powered SIEM, EDR and SOAR platform for modern security operations.

File Explorer

ZIP Download

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - ci.yml
  - trivy.yml
- PULL_REQUEST_TEMPLATE.md
- __init__.py
- criteria.py
- gating.py
- intel.py
- prompts.py
- schemas.py
- utils.py
- __init__.py
- generate_certs.py
- __init__.py
- agent_key.py
- agent_link.py
- attack.py
- config_validation.py
- correlation.py
- evaluation.py
- installers.py
- login_guard.py
- mq.py
- netloc.py
- opensearch.py
- reporting.py
- schema_init.py
- self_defence.py
- sigma.py
- sigma_loader.py
- soar_palette.py
- telemetry_crypto.py
- threat_feeds.py
- tls.py
- triage.py
- version.py
- init.sql
- init_userdb.sql
- - agent-ai-analysis.jpg
  - agent-alerts.jpg
  - agent-overview.jpg
  - asset-inventory-hardware.jpg
  - asset-inventory-network.jpg
  - audit-logs.jpg
  - dashboard.jpg
  - log-explorer.jpg
  - sidebar.jpg
- production-deployment.md
- PROGRESS_REPORT.md
- Sentora_Architecture.md
- update-runbook.md
- - .gitkeep
- corpus_attacks.jsonl
- - vite.svg
- - App.css
  - App.tsx
  - index.css
  - main.tsx
  - vite-env.d.ts
- .gitignore
- eslint.config.js
- index.html
- package-lock.json
- package.json
- README.md
- tsconfig.app.json
- tsconfig.json
- tsconfig.node.json
- vite.config.ts
- __init__.py
- vuln.py
- api_smoke_test.py
- backup_state.py
- build_attack_corpus.py
- build_eval_corpus.py
- generate_telemetry.py
- init_secrets.py
- label_eval_corpus.py
- lock_requirements.py
- rotate_db_password.py
- rule_hit_report.py
- run_eval.py
- __init__.py
- session.py
- ssrf.py
- totp.py
- webauthn.py
- - file_scan.yaml
  - log_paths.yaml
  - rules.yaml
- - init.sql
  - init_sqlite.sql
- - MODULES.md
- - agent_paths.py
  - console.py
  - db.py
  - edr_enforcer.py
  - enc_db.py
  - fim.py
  - inventory.py
  - lateral_movement.py
  - link.py
  - persistence_hunter.py
  - screen_capture.py
  - telemetry_health.py
  - version.py
- .gitignore
- build_agent.ps1
- build_agent.sh
- deploy.ps1
- deploy.sh
- docker-compose.yml
- LICENSE
- main.py
- README.md
- requirements.txt
- Sentora.md
- VERSION
- - benign.yml
  - linux.yml
  - windows.yml
- __init__.py
- conftest.py
- test_agent_api_auth.py
- test_agent_config_persistence.py
- test_agent_console.py
- test_agent_deletion.py
- test_agent_display_name.py
- test_agent_enrolment.py
- test_agent_link.py
- test_agent_link_client.py
- test_agent_logging.py
- test_agent_proxy_status.py
- test_agent_reported_ip.py
- test_agent_restart.py
- test_agent_retention.py
- test_agent_schema_migration.py
- test_agent_self_destruct.py
- test_agent_single_instance.py
- test_agent_sql_parameters.py
- test_agent_trust.py
- test_ai_cache.py
- test_ai_gating.py
- test_ai_intel.py
- test_ai_schema_locks.py
- test_ai_schemas.py
- test_ai_utils.py
- test_api_smoke_test.py
- test_attack_coverage.py
- test_attack_hierarchy.py
- test_auth_wiring.py
- test_automation_endpoint_auth.py
- test_automation_status.py
- test_backup_state.py
- test_build_agent_sh.py
- test_clear_table_dedup.py
- test_collector_isolation.py
- test_collector_survival.py
- test_config_validation.py
- test_console_open_deadline.py
- test_correlation.py
- test_criteria.py
- test_db_pool_leaks.py
- test_db_pool_release.py
- test_design_system.py
- test_detection_rules.py
- test_encrypt_fields_map.py
- test_encrypted_column_widths.py
- test_encryption_actually_applied.py
- test_evaluation.py
- test_ingest_acknowledgement.py
- test_ingest_modes.py
- test_ingest_schema_coverage.py
- test_ingest_schema_locks.py
- test_ingest_tls.py
- test_init_secrets.py
- test_installer_transport.py
- test_key_mismatch_visibility.py
- test_ldap_injection.py
- test_link_frame_priority.py
- test_login_guard.py
- test_module_reference.py
- test_netloc.py
- test_password_policy.py
- test_reporting.py
- test_requirements_lock.py
- test_sanic_listeners.py
- test_screen_capture.py
- test_search.py
- test_second_factor.py
- test_self_defence.py
- test_self_exclusion.py
- test_server_reset_recovery.py
- test_session.py
- test_sigma.py
- test_sigma_all_paths.py
- test_sigma_builtin_rules.py
- test_sigma_evidence.py
- test_sigma_loader.py
- test_soar_dispatch.py
- test_sql_identifiers.py
- test_ssrf.py
- test_startup_ordering.py
- test_swallowed_errors.py
- test_telemetry_crypto.py
- test_telemetry_health.py
- test_threat_feeds.py
- test_tls_certs.py
- test_tls_documentation.py
- test_tls_end_to_end.py
- test_tls_serving.py
- test_triage.py
- test_versioning.py
- test_vuln_scanner.py
- test_webauthn_origin.py
- test_windows_eventlog_cursor.py
.dockerignore
.env.example
.gitattributes
.gitignore
ai_worker.py
app.py
CONTRIBUTING.md
docker-compose.yaml
Dockerfile
LICENSE
pytest.ini
README.md
requirements-dev.txt
requirements.lock
requirements.txt
SECURITY.md
server.py

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

License: AGPL v3 Visit
Python 3.10+ Visit
Built with Sanic Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Self-hosted security stack for small/mid teams that don't have a dedicated
SOC. Drop an agent on each endpoint, point them at the server, and you get
SIEM logs, file integrity, package vulnerabilities, an OpenSearch-powered
log explorer, autonomous AI triage and a SOAR playbook engine, all in one
`docker compose up`.

The "AI" part is a locally-running Ollama model (default `llama3.2:3b`).
Logs never leave the box; there's no OpenAI key, no Anthropic key, no
phone-home. If you want a smarter model and have the RAM, swap it in `.env`.

![Dashboard](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/dashboard.jpg)

---

## What it actually does

- **Collects telemetry** from Windows and Linux agents over a single TCP
  channel. SIEM events, alerts, FIM, packages, network connections,
  open ports, Docker activity, screen frames.
- **Detects with Sigma rules, on the endpoint.** 43 rules covering 47 MITRE
  ATT&CK techniques ship in `conf/sigma/builtin/`; drop community rulesets in
  beside them. Sigma matches *named fields* rather than text, so
  `Image|endswith: '\vssadmin.exe'` cannot be defeated by the word "vssadmin"
  appearing in an unrelated message — and
  `CommandLine|utf16le|base64offset|contains` reads inside a base64
  `-EncodedCommand` payload, where the plaintext command line shows only the
  wrapper. Measured on the eval corpus: 9 of 10 attacks caught by Sigma alone,
  0 of 9 hard negatives falsely flagged. This layer is deterministic and keeps
  working when the model is unavailable.
- **Correlates across events**, which no per-event rule can do. A single failed
  logon is routine; five accounts failing from one source in forty seconds is a
  password spray, and looking at any one of those five events will never tell
  you that. Covers spray, brute force, a success arriving after repeated
  failures, and bursts of account creation or service installs — on both
  platforms, from Windows event IDs or from parsed `auth.log` lines.

Runs at **two vantage points**, because they see different attacks. Per host
  on the agent, where an attack against one machine is visible in full. And
  across hosts in the ingest path, where a spray walked one failure at a time
  over fifty machines shows up — no single agent sees more than one event, and
  that is the more competent attack, since spraying wide and shallow stays
  under both per-account lockout and per-host thresholds.

Total coverage with Sigma: 51 techniques. Every window fires once rather than
  once per event, and every counter is bounded — a counter keyed on an
  attacker-supplied username is a memory exhaustion primitive, not a detection.
- **Maps detections to MITRE ATT&CK, from the rules themselves.** Rules carry
  `tags: attack.t1490`, so there is no hand-kept mapping table to go stale. The
  coverage page separates three states a single "coverage %" would hide:
  covered and seen, covered and quiet, and *not covered at all* — the last
  being the only one where the console's silence means nothing.
- **Triages every event with a local LLM.** Three workers run in parallel:
  one watches every incoming event in real time, one runs operator-driven
  deep scans, and one decides whether to take a defensive action
  (`BLOCK_IP`, `ISOLATE_HOST`, `KILL_PROCESS`, etc.).
- **Shadow mode for the defensive worker.** Flip `AI_SHADOW_MODE=1` and
  every autonomous verdict is staged for human approval in the SOAR Hub
  instead of being dispatched. Useful for tuning the model on real
  traffic before letting it act on its own.
- **Indexes everything in OpenSearch** so you can grep your fleet with
  fuzzy / exact / starts-with queries from one place.
- **Runs SOAR playbooks** built in a small visual editor with multi-step,
  per-node result tracking, can be triggered manually or by AI verdict.
- **Vulnerability scans** every agent's installed packages against OSV
  (online or via an internal mirror).
- **Pulls threat-intel feeds** from abuse.ch (Feodo, ThreatFox, URLhaus)
  into a local indicator table, with staleness pruning and an air-gap
  switch.
- **Validates agent configs before pushing them.** YAML parse, structural
  shape and regex compilation — an invalid regex is valid YAML and silently
  disables the rule containing it.
- **Built-in remote desktop** via WebSocket JPEG streaming, no separate
  VNC install needed on the endpoint.

## What it looks like

The sidebar groups everything into three sections: telemetry (dashboard,
agents, alerts, assets, FIM, logs, AI), automation response
(defensive actions, playbooks, automation rules), and administration.

### Per-agent view

Each enrolled agent has its own page with twelve tabs. The overview
shows live resource meters, the most recent SIEM logs, agent metadata
and a threat summary:

![Agent overview](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/agent-overview.jpg)

Alerts are everything the agent's own correlation rules already flagged.
Severity-coloured, filterable, searchable:

![Agent alerts](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/agent-alerts.jpg)

The AI Analysis tab is the operator-facing side of the local LLM. Manual
and automatic scans both land here. Each insight carries a verdict chip,
confidence, MITRE indicators (when the model returns them), IOCs, next
steps, and a *View Source* button that opens the exact log row the AI
looked at:

![AI analysis](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/agent-ai-analysis.jpg)

### Asset inventory

Hardware, software, and network sockets per agent. Hardware tab lists
every PnP device, software lists installed packages, network lists every
TCP/UDP socket with its owning process:

![Asset inventory: hardware](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/asset-inventory-hardware.jpg)

![Asset inventory: network](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/asset-inventory-network.jpg)

### Log Explorer

Cross-agent search backed by OpenSearch. Pick an agent, pick a dataset
(SIEM events, security alerts, process events, network, FIM, audit
logs), and search. There's also a button to open OpenSearch Dashboards
(Kibana fork) for power users:

![Log Explorer](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/log-explorer.jpg)

### Audit logs

Every login attempt against the platform itself, both local and LDAP,
with result, source IP, and timestamp. Useful when someone is in the
"who-logged-in-when" mood:

![Audit logs](https://raw.githubusercontent.com/d3vhex/Sentora/main/docs/pics/audit-logs.jpg)

---

## Quick start

You'll need Docker 24+ with Compose v2 and Python 3.10+ on the host (only
for the one-time agent build step). The full stack wants ~16 GB RAM,
see [System requirements](#system-requirements) below.

```bash
git clone https://github.com/d3vhex/Sentora.git
cd Sentora

# .env holds your local secrets. Never commit it.
cp .env.example .env

# Generate the machine-generated secrets (FERNET_KEY, RABBITMQ_PASSWORD,
# AGENT_SHARED_SECRET, OPENSEARCH_PASSWORD). Safe to re-run — it never
# overwrites a value that is already set.
python scripts/init_secrets.py

# Then set DB_PASSWORD by hand. Compose refuses to start without it.
# On an existing deployment, rotate it with scripts/rotate_db_password.py
# instead — MySQL fixes the root password at first init, so editing .env
# alone locks the app out rather than changing the account.

# Build the agent binary once. The server serves it via
# /api/agent/download/{linux,windows}; skipping this means agents can't be
# deployed because the download endpoint returns 404.
cd Sentora
./build_agent.sh                 # on Linux/macOS/WSL
# .\build_agent.ps1              # on Windows
cd ..

docker compose up --build -d
```

Open <http://localhost:8000>. Default login is `admin` / `admin123`.
Change it immediately under **Users & Roles**.

Ollama auto-pulls `llama3.2:3b` on first boot. Verify with:

```bash
docker exec sentora-ollama ollama list
```

Deploying an agent: from the **Deploy Agent** page, copy the one-liner
for the OS you want. On the target machine (admin shell), paste it. The
installer downloads the binary, drops a config, enrols with the server,
and registers itself as a scheduled task / systemd unit.

---

## Services in the compose

| Service | Port | Reachable from | Purpose |
| :--- | :--- | :--- | :--- |
| `app` | `:8000` | anywhere | REST API + React UI |
| `ingest` | `:5001` | anywhere | TCP log collector (the agent sends here) |
| `db` | `:3307` | localhost | MySQL 8.0 (3306 inside the network) |
| `rabbitmq` | `:5672` / `:15672` | localhost | Job queue + management UI |
| `ollama` | `:11434` | localhost | Local LLM runtime |
| `opensearch` | `:9200` | localhost | Full-text log search |
| `opensearch-dashboards` | `:5601` | localhost | Optional Kibana-style explorer |
| `ai-worker-{automation,manual,defensive}` |   | — | LLM analysis workers |

Only `app` and `ingest` listen on all interfaces. The rest bind to
`BIND_ADDR` (default `127.0.0.1`), because none of them authenticate in the
default configuration — OpenSearch runs with its security plugin disabled and
Dashboards is an unauthenticated view of every collected log. Expose one by
putting it behind the same reverse proxy and auth as `app`, not by widening
`BIND_ADDR`.

The "Open Dashboards" button in Log Explorer links to port 5601 on the
server's hostname, so it works from the host itself; remote operators need
that reverse proxy.

---

## System requirements

Idle footprint:

- Ollama (`llama3.2:3b`): ~3 GB, more under inference
- OpenSearch: ~2 GB default heap, disk grows with retention
- MySQL: 500 MB – 1 GB
- RabbitMQ: ~300 MB
- Sanic + ingest + 3 AI workers: ~1 GB combined

If you're tight on RAM, swap to `qwen2.5:1.5b` or another small Ollama
model and shrink the OpenSearch heap. A GPU isn't required but Ollama
will use it automatically if present.

---

## Defensive AI auto-actions

When the defensive worker's verdict is `ACT` with confidence ≥
`AI_AUTO_ACT_CONF` (default `0.75`) and the recommended action is on the
safe-list below, the worker queues the action straight into the agent's
`automations` table:

```
BLOCK_IP        KILL_PROCESS      RESTART_SERVICE   ISOLATE_HOST
DISABLE_USER    QUARANTINE_FILE   SUSPEND_PROCESS   LOGOFF_USER
CONTAINER_ISOLATE   CONTAINER_STOP   CONTAINER_KILL
```

Anything outside that list (arbitrary `RUN_CMD`, `DELETE_FILE`, etc.)
gets downgraded to an advisory insight. The operator has to dispatch
it manually from the SOAR Hub. Auto-dispatched actions show a red AUTO
chip in the UI.

To disable autonomy entirely, set `AI_AUTO_ACT_CONF=1.0` in `.env`. To
disable the periodic defensive sweep, set `AI_DEFENSIVE_SWEEP_ENABLED=0`.

### Shadow mode

Set `AI_SHADOW_MODE=1` in `.env` and the defensive worker stops firing
real actions. Verdicts that would have triggered an autonomous response
are saved as **proposals** instead, with `source_file = AI_DEFENSIVE_SHADOW`
and `shadow_status = pending`. The operator reviews each one from
**SOAR Hub > Shadow Queue** and either:

- **Approve** > the real SOAR action (`call_agent_soar`) fires and the
  proposal is marked `approved` (with timestamp + operator name).
- **Reject** > the proposal is marked `rejected` with an optional note.
  No action is taken.

Proposals never expire; nothing decides for you. Useful for letting the
model run on production telemetry while you build confidence in its
verdicts before unleashing real `BLOCK_IP` / `ISOLATE_HOST` etc.

---

## Security notes

### Authentication

The UI authenticates with a server-side session: login issues an opaque token
in an `HttpOnly` cookie, and `userdb.sessions` is the authority. Only the
SHA-256 of the token is stored, so a database dump yields nothing presentable.

Two clocks apply, both configurable in `.env`:

Sessions are revoked immediately on password change, admin password reset,
role change and account deletion — an admin removing someone's access no
longer leaves their open tab working.

Every route is **deny-by-default**: without a valid session a request is
rejected before the handler runs. The exceptions are the login endpoint, the
SPA shell, static assets, and the agent-facing endpoints, which authenticate
with `X-Agent-Key` or an enrollment token instead.

`X-User-ID` is still sent by the frontend, but it is no longer identity — the
server validates it against the session and rejects a mismatch. Because
browsers cannot attach custom headers to cross-site requests without a CORS
preflight, requiring it on state-changing requests backs up `SameSite` as a
second CSRF control.

Route protection is declared with `@require_permission(...)` and enforced by
middleware through a registry, so it applies regardless of which side of
`@app.route` the decorator sits on. The boot log prints the tally:

```
[Auth] Routes: <n> permission-gated, <n> session-only, <n> public.
```

If that line reports `0 permission-gated`, RBAC is not being enforced — treat
it as an outage.

Every route must be one of three things: permission-gated, listed in
`_PUBLIC_HANDLERS`, or named in `SESSION_ONLY_HANDLERS` in
`tests/test_auth_wiring.py` with a comment saying why session alone is
enough. A test asserts it, so a new route cannot quietly arrive ungoverned —
which is how `run_playbook`, `delete_soar_action` and `test_ldap_connection`
had ended up reachable by any account that could log in.

### Login throttling

Five failed attempts for one account, or twenty from one address, inside
fifteen minutes, and further attempts are refused with `429` until the window
passes. Counted from `login_logs`, which was already recording every failure
and which nothing read — bcrypt was the only brake on online guessing.

The check runs before the password comparison, so it also removes the timing
difference between a known and an unknown username. It fails open if
`login_logs` is unreachable: a login page that cannot be reached because the
audit table is down is its own outage.

### Client addresses behind a proxy

`X-Forwarded-For` is honoured only from a peer listed in `TRUSTED_PROXIES`
(comma-separated addresses or CIDRs, empty by default). With nothing in front
of the app the header is attacker-supplied, so believing it unconditionally —
which is what this replaced — let a caller write any address into the audit
trail and reset their own rate limit in the same request.

```
TRUSTED_PROXIES=10.0.0.0/8,192.168.1.5
```

Leave it empty when the app is reached directly.

### How the server reaches an agent

It does not. The agent opens a WebSocket to the server and keeps it, and every
server-to-agent request rides that one connection — config, SOAR, restart,
uninstall, the screen stream and the console. The agent serves nothing, so
there is nothing on an endpoint to reach, scan or authenticate to.

It does bind one socket: `127.0.0.1:9098`, used as a mutex rather than as a
service. It never accepts a connection — the bind failing is the whole signal,
and it is on loopback — and it exists because the installer registers a
watchdog task that launches the agent every fifteen minutes, which without a
guard would stack up a second agent on every tick.

The channel is authenticated once, when the agent dials in, against
`agent_identities` — this agent's own enrolment key, never the fleet-wide
secret, because `/self_destruct` rides this connection and a leaked master key
should not uninstall every endpoint at once.

This is also why the agent works behind NAT and behind a host firewall,
neither of which the previous arrangement survived, and why the installers
*remove* the inbound rule for 9099 rather than adding one.

It used to be the other way round. The agent ran a management API on
`0.0.0.0:9099` as SYSTEM or root, and the server dialled it — which meant an
address to guess, a Windows firewall rule a session-0 service cannot prompt
for, a `ufw` rule on Linux, and `/self_destruct` exposed on every endpoint in
the fleet. Worse, a permissive branch accepted any non-empty `X-Agent-Key`
whenever `AGENT_MASTER_SECRET` was unset on the host, and nothing in this
repository ever set it, so every default installation ran that way. An EDR
that fails open is worse than no EDR, because the console reports the endpoint
as protected.

That was fixed by authenticating the routes properly. Then the routes went.

### CORS

`CORS_ORIGINS` defaults to empty. In the normal deployment this app serves the
SPA itself, so requests are same-origin and no entry is needed. A wildcard is
rejected outright: browsers refuse `Access-Control-Allow-Origin: *` on any
request carrying cookies. Split-origin deployments must list explicit origins
and set `SESSION_COOKIE_SAMESITE=None` with `SESSION_COOKIE_SECURE=1`.

### Default secrets

`.env.example` ships with placeholders. The real `.env` is git-ignored.
Rotate these before exposing the platform to anything beyond `localhost`:

- `DB_PASSWORD`
- `AGENT_SHARED_SECRET` (agent auth fallback). Auto-generated on first
  boot if unset.

The `admin / admin123` login no longer needs remembering: the seeded account
is created with `must_change_password`, and while that is set the session can
reach nothing but `/change-password`. Enforced in middleware rather than in
the UI, because a flag the front end is trusted to honour is a suggestion and
the API answers curl too.

### TLS certificates

Nothing ships a private key. A working `certs/server.key` and
`certs/rootCA.key` used to be committed, which gave every deployment the same
TLS identity and published it: anyone who had ever cloned the repository held
the key, so the certificate proved nothing about who was on the other end.

With `TLS_ENABLED=1` and no certificate present, the app generates one on
first boot. Each install gets its own key and the key never leaves the machine
that made it. `certs/*.key` and `certs/*.crt` are git-ignored.

The CA is self-signed, so browsers warn unless you trust it explicitly. That
warning is honest — prefer it to a shared secret that produces no warning at
all. For anything public, point `TLS_CERT` / `TLS_KEY` at a real certificate;
when they are set and missing, the app says so rather than substituting a
self-signed one.

To regenerate by hand:

```bash
python certs/generate_certs.py --force
```

**The old keys are still in git history.** Treat the pair that shipped before
this change as burned; new installs no longer use it.

### Local Fernet keys

The server uses two Fernet keys, both auto-generated on first boot:

`chmod 600` both. Back them up. Losing either makes the corresponding
encrypted data unreadable. There is no in-place rotation yet.

### Threat intel

Two independent mechanisms, both optional:

**Per-verdict enrichment** (`ai/intel.py`). The AI worker cross-checks
indicators found in a log against AlienVault OTX and VirusTotal. Needs
`OTX_API_KEY` / `VT_API_KEY`; unset means no external call at all.

**Indicator feeds** (`core/threat_feeds.py`). Populates the `threat_intel`
table hourly from abuse.ch — Feodo Tracker (botnet C2 addresses), ThreatFox
(mixed IoCs with a confidence score) and URLhaus (malware-distributing URLs).

Indicators carry `last_seen` and are pruned after `THREAT_INTEL_STALE_DAYS`
(default 30): an address that hosted a C2 last quarter usually belongs to
someone else now, and keeping it produces false positives indefinitely. Each
feed is capped at `THREAT_INTEL_MAX_PER_FEED` rows because the table is read
on the alert path.

abuse.ch has been moving downloads behind a free account key. A feed
returning 401/403 says so in the server log; set `THREAT_INTEL_AUTH_KEY`.

Check what actually arrived:

```bash
docker logs sentora-server | grep ThreatIntel
```

### Air-gap mode

```ini
OSV_MODE=mirror
OSV_MIRROR_URL=http://osv.internal

THREAT_INTEL_MODE=off
# or serve the feeds internally:
# THREAT_INTEL_FEODO_URL=http://mirror.internal/feodo.json
```

With those set, plus `OTX_API_KEY` / `VT_API_KEY` unset, nothing leaves the
network. Fonts are bundled, Ollama is local, no CDN is contacted.

### Fleet exposure

`/api/exposure/report` counts unpatched packages and file-integrity events
across the fleet, per agent, worst first. It reports its own coverage:
`complete: false` when an agent could not be read, because a total over half
the fleet is not a fleet total.

There is deliberately no score. The endpoint previously returned
`100 - vulns*2 - fim*5` as a "compliance score" — that maps to no framework,
does not scale with fleet size, and pins to zero on any real fleet. Severity
grading is absent for the same reason: `vulnerabilities_report` has no
severity column and its fields are encrypted at rest, so any grade would have
to be invented.

### Agent config validation

`POST /<agent>/config/<type>` validates before anything reaches a sensor:
YAML parse, structural shape, and — the layer that matters — **regex
compilation**. An invalid regex is perfectly valid YAML and silently disables
the category containing it, so a syntax-only check would push it straight to
the endpoint. The editor lints against the same endpoint as you type and
reports issues with clickable line numbers.

---

## Architecture overview

```
 Agent (Win / Linux)
    │  TCP frames + REST polling
    ▼
 ingest (:5001) ──► RabbitMQ ──► AI worker fleet (3 modes)
    │                                  │
    ▼                                  ▼
 MySQL (per-agent <name>_db)    ai_analysis_results
    │
    ▼
 app (Sanic :8000)  ──► React UI + REST + WebSocket screen proxy
```

The deeper version (per-module layout, schema, AI pipeline, SOAR
autonomy, air-gap surfaces) lives in
[docs/Sentora_Architecture.md](docs/Sentora_Architecture.md).

Operational docs:

---

## Development setup

```bash
# 1. Database. Only init_userdb.sql — it creates and selects `userdb`.
#
#    db/init.sql is NOT a server-init script. It is the per-agent schema
#    template, applied by server.create_tables_if_not_exist() after
#    connecting to that agent's own database, which is why it contains no
#    CREATE DATABASE or USE. Running it standalone fails at line 5 with
#    "No database selected" — the same way it broke every first-time
#    `docker compose up` while it was mounted into the MySQL init directory.
mysql -u root -p < db/init_userdb.sql

# 2. Backend. requirements.lock pins every version the image is built
#    from; requirements.txt is the loose list it was resolved from.
pip install -r requirements.lock
python app.py

# 3. Ingest (separate terminal)
python server.py

# 4. Frontend dev server
cd frontend
npm install
npm run dev
```

### AI workers manually

Same script, three roles:

```bash
WORKER_TYPE=automation python ai_worker.py
WORKER_TYPE=manual     python ai_worker.py
WORKER_TYPE=defensive  python ai_worker.py
```

Production: let `docker-compose.yaml` do it.

---

## Contributing

PRs welcome. Before opening:

1. Fork → branch → PR against `main`.
2. Run the checks:

```bash
pytest -ra                                   # no MySQL or RabbitMQ needed
python -m compileall -q app.py core security
cd frontend && npx tsc --noEmit && npm run build && cd ..

# With the stack up — enumerates every route and calls it twice
python scripts/api_smoke_test.py
```

3. New endpoints must be wrapped in `@require_permission(...)`. The boot log
   prints the tally; if it reports `0 permission-gated`, something is wrong
   with the wiring, not with your route.
4. Anything that reaches an agent or an external host needs validation on the
   server side, not only in the browser. Two implementations drift, and the
   browser's copy is the one operators end up trusting.

For anything bigger than a fix, open an issue first so we can align on
the approach.

---

## Project layout

```
.
├── app.py                     # Sanic API + React SPA host
├── server.py                  # TCP ingest
├── ai_worker.py               # AI worker fleet (3 modes)
├── ai/
│   ├── utils.py               # LLM helpers, AI cache, SOAR queueing
│   └── intel.py               # OTX / VT per-verdict enrichment (opt-in)
├── core/
│   ├── mq.py                  # RabbitMQ publisher
│   ├── opensearch.py          # OpenSearch index/search
│   ├── config_validation.py   # Agent YAML validation (parse, shape, regex)
│   └── threat_feeds.py        # abuse.ch indicator feeds
├── security/
│   ├── session.py             # Server-side session store
│   └── ssrf.py                # Proxy destination rules
├── scanners/
│   └── vuln.py                # Server-side OSV scanner
├── scripts/
│   ├── init_secrets.py        # Generate the secrets .env needs
│   ├── rotate_db_password.py  # Rotate the MySQL root password safely
│   └── api_smoke_test.py      # Exercise every route against a live server
├── tests/                     # pytest; no MySQL or RabbitMQ required
├── frontend/                  # React 18 + TS SPA
│   └── src/lib/               # Shared logic (playbook action catalogue)
├── Sentora/                   # Cross-platform agent
├── certs/                     # Self-signed dev certs
├── docs/                      # Architecture + screenshots
└── docker-compose.yaml
```

---

## License

AGPL-3.0. See [LICENSE](LICENSE).

Use, modify, redistribute. The thing AGPL adds on top of regular GPL:
if you run a modified version on a network server where other users
interact with it, you must publish the modifications under AGPL too.

- Self-hosting for internal use → no source-disclosure obligation.
- Public-facing SaaS on top of a modified Sentora → you must publish
  the modifications.
- Want to ship a closed-source derivative or skip the network-copyleft
  clause? A commercial licence waiver is available. Contact the author.

The "Sentora" name and logo are trademarks of the project authors and
are not covered by AGPL. Fork freely, but rename if you redistribute as
your own product.

---

## What's not in Community Edition

Community Edition has zero artificial caps: no agent limit, no
retention limit, no feature gating on the core. Run it as wide as your
hardware allows.

The paid Pro / Enterprise distribution adds enterprise-glue features
(SAML/SCIM SSO, multi-tenancy, compliance reports, HA, WORM audit,
signed air-gap update bundles, 4-eyes SOAR approvals, premium
ticketing/SIEM forwarders). The core detection capability never gets
moved behind that wall.

If any of that matters for your deployment,
[reach out](mailto:oguzhanbayarslan@gmail.com).

Sentora

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README