# andy1218100/shinji-soc architecture

> Architecture diagram of the GitHub repository andy1218100/shinji-soc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andy1218100/shinji-soc
- Repository: https://github.com/andy1218100/shinji-soc

## Overview

Shinji SOC is a self-hosted SOC: an administrator enrolls monitored Linux hosts, agents send telemetry and inventory, and the server stores it, detects security events and vulnerabilities, then presents findings for review and approved response. The graph also preserves the documented local-AI, notifications, geolocation, MFA, and optional MCP audit capabilities. Agent-to-server ingestion and server startup wiring are visible in excerpts; several product branches are documented in the README but their internal calls were not sampled, so those links are omitted or marked unverified.

Main entry points: [`agent/main.py`](https://github.com/andy1218100/shinji-soc/blob/main/agent/main.py) (Agent runtime), [`server/app/main.py`](https://github.com/andy1218100/shinji-soc/blob/main/server/app/main.py) (Web API), [`server/app/services/vuln_scan.py`](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/vuln_scan.py) (Vulnerability scanning), [`server/app/api/hosts.py`](https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/hosts.py) (Host and telemetry APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Host agent"]
  node_agent_runtime["Agent runtime<br/>[main.py]"]
  node_discovery["Host discovery<br/>[discovery.py]"]
  node_telemetry["Metrics and logs<br/>[metrics.py]"]
  node_auth_watch["Login watcher<br/>[auth_watch.py]"]
  node_process_watch["Process watcher<br/>[process_watch.py]"]
end

subgraph group_server["SOC server"]
  node_api["Web API<br/>[main.py]"]
  node_hosts_api["Host and telemetry APIs<br/>[hosts.py]"]
  node_auth_api["MFA and account access<br/>[auth.py]"]
  node_auth_core["Authentication core<br/>[auth.py]"]
  node_database[("SOC database<br/>[db.py]")]
  node_host_records["Hosts and inventory<br/>[host.py]"]
end

subgraph group_security["Detection and response"]
  node_security_records["Security event records<br/>[security.py]"]
  node_ids["Intrusion detection<br/>[ids.py]"]
  node_commands["Approved response commands<br/>[commands.py]"]
end

subgraph group_operations["SOC operations"]
  node_dashboard["SOC dashboard<br/>[dashboard.py]"]
  node_alerting["Threshold alerting<br/>[alerting.py]"]
  node_vuln_scan["Vulnerability scanning<br/>[vuln_scan.py]"]
  node_vuln_records["Vulnerability findings<br/>[vulnerability.py]"]
  node_ai["Local AI explanations<br/>[ai.py]"]
  node_geoip["Attack geolocation<br/>[geoip.py]"]
  node_audit["AI text audit<br/>[audit.py]"]
end

subgraph group_integrations["External integrations"]
  node_mcp["MCP audit service<br/>[server.py]"]
  node_osv["OSV vulnerability data"]
  node_ollama["Ollama"]
  node_notification_channels["Notification channels"]
end

node_admin(("Administrator"))
node_linux(("Monitored Linux host"))

node_linux -->|"runs"| node_agent_runtime
node_agent_runtime -->|"collects inventory"| node_discovery
node_agent_runtime -->|"collects metrics"| node_telemetry
node_agent_runtime -->|"reads login events"| node_auth_watch
node_agent_runtime -->|"monitors processes"| node_process_watch
node_agent_runtime -->|"sends telemetry"| node_api
node_admin -->|"reviews findings"| node_dashboard
node_api -->|"routes requests"| node_hosts_api
node_api -->|"routes requests"| node_auth_api
node_api -->|"starts background task"| node_alerting
node_api -->|"starts background task"| node_vuln_scan
node_api -->|"routes requests"| node_dashboard
node_hosts_api -->|"reads and updates"| node_host_records
node_hosts_api -->|"queries records"| node_database
node_auth_api -->|"verifies credentials"| node_auth_core
node_auth_api -->|"loads account"| node_database
node_auth_core -.->|"stores account data"| node_database
node_ids -.->|"records detections"| node_security_records
node_alerting -.->|"sends alerts"| node_notification_channels
node_vuln_scan -->|"stores findings"| node_vuln_records
node_vuln_scan -->|"queries vulnerabilities"| node_osv
node_vuln_scan -->|"requests explanations"| node_ai
node_ai -.->|"uses local model"| node_ollama
node_dashboard -->|"uses attack locations"| node_geoip
node_admin -.->|"approves response"| node_commands
node_mcp -.->|"requests text audits"| node_audit
node_audit -->|"reviews AI text"| node_ai

click node_agent_runtime "https://github.com/andy1218100/shinji-soc/blob/main/agent/main.py"
click node_discovery "https://github.com/andy1218100/shinji-soc/blob/main/agent/discovery.py"
click node_telemetry "https://github.com/andy1218100/shinji-soc/blob/main/agent/metrics.py"
click node_auth_watch "https://github.com/andy1218100/shinji-soc/blob/main/agent/auth_watch.py"
click node_process_watch "https://github.com/andy1218100/shinji-soc/blob/main/agent/process_watch.py"
click node_api "https://github.com/andy1218100/shinji-soc/blob/main/server/app/main.py"
click node_hosts_api "https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/hosts.py"
click node_auth_api "https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/auth.py"
click node_auth_core "https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/auth.py"
click node_database "https://github.com/andy1218100/shinji-soc/blob/main/server/app/core/db.py"
click node_host_records "https://github.com/andy1218100/shinji-soc/blob/main/server/app/models/host.py"
click node_security_records "https://github.com/andy1218100/shinji-soc/blob/main/server/app/models/security.py"
click node_ids "https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/ids.py"
click node_commands "https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/commands.py"
click node_dashboard "https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/dashboard.py"
click node_alerting "https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/alerting.py"
click node_vuln_scan "https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/vuln_scan.py"
click node_vuln_records "https://github.com/andy1218100/shinji-soc/blob/main/server/app/models/vulnerability.py"
click node_ai "https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/ai.py"
click node_geoip "https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/geoip.py"
click node_audit "https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/audit.py"
click node_mcp "https://github.com/andy1218100/shinji-soc/blob/main/tools/mcp_audit/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_runtime,node_discovery,node_telemetry,node_auth_watch,node_process_watch toneBlue
class node_api,node_hosts_api,node_auth_api,node_auth_core,node_database,node_host_records toneAmber
class node_security_records,node_ids,node_commands toneMint
class node_dashboard,node_alerting,node_vuln_scan,node_vuln_records,node_ai,node_geoip,node_audit toneRose
class node_mcp,node_osv,node_ollama,node_notification_channels,node_admin,node_linux toneIndigo
```

## Components

### Host agent

- [Agent runtime](https://github.com/andy1218100/shinji-soc/blob/main/agent/main.py): `agent/main.py`
- [Host discovery](https://github.com/andy1218100/shinji-soc/blob/main/agent/discovery.py): `agent/discovery.py`
- [Metrics and logs](https://github.com/andy1218100/shinji-soc/blob/main/agent/metrics.py): `agent/metrics.py`
- [Login watcher](https://github.com/andy1218100/shinji-soc/blob/main/agent/auth_watch.py): `agent/auth_watch.py`
- [Process watcher](https://github.com/andy1218100/shinji-soc/blob/main/agent/process_watch.py): `agent/process_watch.py`

### SOC server

- [Web API](https://github.com/andy1218100/shinji-soc/blob/main/server/app/main.py): `server/app/main.py`
- [Host and telemetry APIs](https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/hosts.py): `server/app/api/hosts.py`
- [MFA and account access](https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/auth.py): `server/app/api/auth.py`
- [Authentication core](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/auth.py): `server/app/services/auth.py`
- [SOC database](https://github.com/andy1218100/shinji-soc/blob/main/server/app/core/db.py): `server/app/core/db.py`
- [Hosts and inventory](https://github.com/andy1218100/shinji-soc/blob/main/server/app/models/host.py): `server/app/models/host.py`

### Detection and response

- [Security event records](https://github.com/andy1218100/shinji-soc/blob/main/server/app/models/security.py): `server/app/models/security.py`
- [Intrusion detection](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/ids.py): `server/app/services/ids.py`
- [Approved response commands](https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/commands.py): `server/app/api/commands.py`

### SOC operations

- [SOC dashboard](https://github.com/andy1218100/shinji-soc/blob/main/server/app/api/dashboard.py): `server/app/api/dashboard.py`
- [Threshold alerting](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/alerting.py): `server/app/services/alerting.py`
- [Vulnerability scanning](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/vuln_scan.py): `server/app/services/vuln_scan.py`
- [Vulnerability findings](https://github.com/andy1218100/shinji-soc/blob/main/server/app/models/vulnerability.py): `server/app/models/vulnerability.py`
- [Local AI explanations](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/ai.py): `server/app/services/ai.py`
- [Attack geolocation](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/geoip.py): `server/app/services/geoip.py`
- [AI text audit](https://github.com/andy1218100/shinji-soc/blob/main/server/app/services/audit.py): `server/app/services/audit.py`

### External integrations

- [MCP audit service](https://github.com/andy1218100/shinji-soc/blob/main/tools/mcp_audit/server.py): `tools/mcp_audit/server.py`
- **OSV vulnerability data**
- **Ollama**
- **Notification channels**

### Other components

- **Administrator**
- **Monitored Linux host**

## Connections

- Monitored Linux host → Agent runtime: runs
- Agent runtime → Host discovery: collects inventory (evidence: `agent/main.py`)
- Agent runtime → Metrics and logs: collects metrics (evidence: `agent/main.py`)
- Agent runtime → Login watcher: reads login events (evidence: `agent/main.py`)
- Agent runtime → Process watcher: monitors processes (evidence: `agent/main.py`)
- Agent runtime → Web API: sends telemetry (evidence: `agent/main.py`)
- Administrator → SOC dashboard: reviews findings
- Web API → Host and telemetry APIs: routes requests (evidence: `server/app/main.py`)
- Web API → MFA and account access: routes requests (evidence: `server/app/main.py`)
- Web API → Threshold alerting: starts background task (evidence: `server/app/main.py`)
- Web API → Vulnerability scanning: starts background task (evidence: `server/app/main.py`)
- Web API → SOC dashboard: routes requests (evidence: `server/app/main.py`)
- Host and telemetry APIs → Hosts and inventory: reads and updates (evidence: `server/app/api/hosts.py`)
- Host and telemetry APIs → SOC database: queries records (evidence: `server/app/api/hosts.py`)
- MFA and account access → Authentication core: verifies credentials (evidence: `server/app/api/auth.py`)
- MFA and account access → SOC database: loads account (evidence: `server/app/api/auth.py`)
- Authentication core → SOC database: stores account data
- Intrusion detection → Security event records: records detections
- Threshold alerting → Notification channels: sends alerts
- Vulnerability scanning → Vulnerability findings: stores findings (evidence: `server/app/services/vuln_scan.py`)
- Vulnerability scanning → OSV vulnerability data: queries vulnerabilities (evidence: `server/app/services/vuln_scan.py`)
- Vulnerability scanning → Local AI explanations: requests explanations (evidence: `server/app/services/vuln_scan.py`)
- Local AI explanations → Ollama: uses local model
- SOC dashboard → Attack geolocation: uses attack locations (evidence: `server/app/api/dashboard.py`)
- Administrator → Approved response commands: approves response
- MCP audit service → AI text audit: requests text audits
- AI text audit → Local AI explanations: reviews AI text (evidence: `server/app/services/audit.py`)
