ThreatChain SIEM

Install the agent on Linux, macOS, or Windows, stand up a server (on-prem or on a single VPS), point the agents at it over mTLS, and get real-time alerts on process, file, log, and Windows Event Log activity.

Architecture

• Agent — a Python daemon on every monitored host. Tails syslog / Windows Event Log / macOS unified log, hashes critical files (FIM), watches processes, and sends events over mTLS to the server.
• Server — a FastAPI service ingesting agent events, running detection rules, storing alerts, serving a dashboard, and fanning out to alert channels (Discord, Telegram, email, webhook).
• PKI — a local CA signs both the server cert and every agent cert. No cert, no events.

No cloud dependency. No SaaS egress. Runs on your hardware.

Platform support

The agent is a pure-Python program and runs on any system with Python 3.10 or newer. Capabilities vary by platform:

Server runs on Linux (Ubuntu 22.04+ / Debian 12+). Windows and macOS aren't supported as server hosts.

Server install

Run on one Linux host — a $5/mo VPS or an on-prem box is plenty. All commands assume root or sudo.

1. Install packages

   apt-get update
   apt-get install -y python3 python3-venv python3-pip openssl git

2. Clone and install

   mkdir -p /opt/tcsiem
   cd /opt/tcsiem
   git clone https://github.com/threatchain/threatchain-siem.git app
   python3 -m venv venv
   ./venv/bin/pip install -r app/requirements.txt

3. Generate PKI

   mkdir -p /etc/tcsiem/pki
   cd /etc/tcsiem/pki
   openssl genrsa -out ca.key 4096
   openssl req -x509 -new -key ca.key -days 3650 \
     -subj "/CN=ThreatChain SIEM CA" -out ca.crt
   
   # Replace <server-host> with the DNS name or IP agents will use
   openssl genrsa -out server.key 2048
   openssl req -new -key server.key -subj "/CN=<server-host>" -out server.csr
   openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
     -CAcreateserial -days 825 -out server.crt \
     -extfile <(printf "subjectAltName=DNS:<server-host>,IP:<server-ip>")
   
   chmod 600 *.key

4. Configure

   cat > /etc/tcsiem/server.env <<EOF
   SIEM_HMAC_SECRET=$(openssl rand -hex 32)
   TCSIEM_ADMIN_TOKEN=$(openssl rand -hex 24)
   TCSIEM_PKI_DIR=/etc/tcsiem/pki
   SIEM_RULES_DIR=/etc/tcsiem/rules
   EOF
   chmod 600 /etc/tcsiem/server.env
   mkdir -p /etc/tcsiem/rules /var/lib/tcsiem /var/log/tcsiem
   useradd -r -s /sbin/nologin tcsiem
   chown -R tcsiem: /var/lib/tcsiem /var/log/tcsiem

   Save the admin token. It's the only credential that issues agent certs and reaches admin endpoints. Lose it, regenerate and re-enroll every agent.
5. Systemd + start

   cat > /etc/systemd/system/tcsiem-server.service <<EOF
   [Unit]
   Description=ThreatChain SIEM Server
   After=network-online.target
   
   [Service]
   Type=simple
   User=tcsiem
   Group=tcsiem
   EnvironmentFile=/etc/tcsiem/server.env
   WorkingDirectory=/opt/tcsiem/app
   ExecStart=/opt/tcsiem/venv/bin/uvicorn server.api.app:app \\
     --host 0.0.0.0 --port 8403 --workers 4 \\
     --ssl-keyfile /etc/tcsiem/pki/server.key \\
     --ssl-certfile /etc/tcsiem/pki/server.crt \\
     --ssl-ca-certs /etc/tcsiem/pki/ca.crt
   Restart=always
   
   [Install]
   WantedBy=multi-user.target
   EOF
   systemctl daemon-reload && systemctl enable --now tcsiem-server
   ufw allow 8403/tcp

Agent install

Pick your OS. The agent software and agent.yaml schema are identical across platforms — only the install commands and service wrapper differ.

Before any OS-specific steps, issue a cert for this agent from the server host:

# Run on the SERVER host — produces a JSON bundle with the agent's cert + key
AGENT_ID=$(uuidgen)
curl -sS -X POST https://<server-host>:8403/admin/enroll \
  -H "X-Admin-Token: $TCSIEM_ADMIN_TOKEN" \
  -d "{\"agent_id\":\"$AGENT_ID\"}" \
  --cacert /etc/tcsiem/pki/ca.crt \
  -o agent-bundle-$AGENT_ID.json
echo "AGENT_ID=$AGENT_ID"
# Copy agent-bundle-$AGENT_ID.json securely to the target host

Verify the connection

On the server, tail the ingest log. Each enrolled agent heartbeats within 60 seconds regardless of OS:

journalctl -u tcsiem-server -f | grep heartbeat

Or query the admin API:

curl -sS https://<server-host>:8403/admin/agents \
  -H "X-Admin-Token: $TCSIEM_ADMIN_TOKEN" \
  --cacert /etc/tcsiem/pki/ca.crt | jq

Every enrolled agent shows up with its platform field set to linux, darwin, or win32 along with last-seen timestamp.

Detection rules

Rules live in /etc/tcsiem/rules/*.yaml on the server. Ships with 52 built-in rules across five categories:

Rules match against normalized events — the server treats a Windows 4625 (failed logon) and a Linux authentication failure as equivalent for cross-platform rules like "5+ auth failures in 60s".

Write a custom rule — put this in /etc/tcsiem/rules/my-rule.yaml on the server:

id: CUSTOM-001
name: auth failure spike
source: auth
match:
  any:
    - pattern: "authentication failure"          # Linux / macOS syslog
    - windows_event_id: 4625                  # Windows failed logon
threshold:
  count: 5
  window_s: 60
severity: high
alert: "5+ auth failures in 60s on {host} ({platform})"

Reload without restart:

curl -X POST https://<server-host>:8403/admin/reload-rules \
  -H "X-Admin-Token: $TCSIEM_ADMIN_TOKEN" --cacert /etc/tcsiem/pki/ca.crt

Dashboard

Hit https://<server-host>:8403/ in a browser. Three tabs:

• Alerts — timeline of triggered rules, sortable by severity/host/platform. Click for the raw event.
• Agents — health grid with OS icons (penguin / apple / windows), last-seen time, event-rate sparkline.
• Search — full-text search across the last 30 days of events.

Alerts

Each rule forwards to any combination of channels. Add to /etc/tcsiem/server.env:

ALERT_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
ALERT_TELEGRAM_BOT_TOKEN=123456:ABC...
ALERT_TELEGRAM_CHAT_ID=@your_channel
ALERT_WEBHOOK_URL=https://hooks.example.com/siem
[email protected]
ALERT_SMTP_PASS=app-password
[email protected]

Restart the server to pick up new channel config.

Day-2 operations

• Upgrade a Linux/macOS agent: cd /opt/tcsiem/app && git pull && pip install -r requirements-agent.txt && systemctl restart tcsiem-agent (or launchctl kickstart on macOS)
• Upgrade a Windows agent: nssm stop TCSIEMAgent; cd "C:\Program Files\tcsiem"; git pull; .\venv\Scripts\pip install -r requirements-agent.txt; nssm start TCSIEMAgent
• Rotate agent cert — re-run enroll with the same agent_id. The old cert is revoked immediately.
• Backup — nightly snapshot of /var/lib/tcsiem/ (SQLite DB) + /etc/tcsiem/pki/ (CA). Without the CA you cannot issue new agent certs.
• Log rotation — systemd handles it on Linux; on macOS use newsyslog.d; on Windows NSSM supports rotation flags (nssm set TCSIEMAgent AppRotateFiles 1).

Troubleshooting

Still stuck? Contact support with relevant logs attached — journalctl -u tcsiem-server -n 200 on Linux, C:\ProgramData\tcsiem\agent\logs\agent.err on Windows, /var/log/tcsiem-agent.err on macOS.