How andy1218100/shinji-soc works
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 Agent runtime · app/main.py Web API · vuln_scan.py Vulnerability scanning · hosts.py Host and telemetry APIs
Components 27
Host agent
- Agent runtime
agent/main.py - Host discovery
agent/discovery.py - Metrics and logs
agent/metrics.py - Login watcher
agent/auth_watch.py - Process watcher
agent/process_watch.py
SOC server
- Web API
server/app/main.py - Host and telemetry APIs
server/app/api/hosts.py - MFA and account access
server/app/api/auth.py - Authentication core
server/app/services/auth.py - SOC database
server/app/core/db.py - Hosts and inventory
server/app/models/host.py
Detection and response
- Security event records
server/app/models/security.py - Intrusion detection
server/app/services/ids.py - Approved response commands
server/app/api/commands.py
SOC operations
- SOC dashboard
server/app/api/dashboard.py - Threshold alerting
server/app/services/alerting.py - Vulnerability scanning
server/app/services/vuln_scan.py - Vulnerability findings
server/app/models/vulnerability.py - Local AI explanations
server/app/services/ai.py - Attack geolocation
server/app/services/geoip.py - AI text audit
server/app/services/audit.py
External integrations
- MCP audit service
tools/mcp_audit/server.py - OSV vulnerability data
- Ollama
- Notification channels
Other components
- Administrator
- Monitored Linux host
Connections 27
- Monitored Linux host → Agent runtime: runs
- Agent runtime → Host discovery: collects inventory
agent/main.py - Agent runtime → Metrics and logs: collects metrics
agent/main.py - Agent runtime → Login watcher: reads login events
agent/main.py - Agent runtime → Process watcher: monitors processes
agent/main.py - Agent runtime → Web API: sends telemetry
agent/main.py - Administrator → SOC dashboard: reviews findings
- Web API → Host and telemetry APIs: routes requests
server/app/main.py - Web API → MFA and account access: routes requests
server/app/main.py - Web API → Threshold alerting: starts background task
server/app/main.py - Web API → Vulnerability scanning: starts background task
server/app/main.py - Web API → SOC dashboard: routes requests
server/app/main.py - Host and telemetry APIs → Hosts and inventory: reads and updates
server/app/api/hosts.py - Host and telemetry APIs → SOC database: queries records
server/app/api/hosts.py - MFA and account access → Authentication core: verifies credentials
server/app/api/auth.py - MFA and account access → SOC database: loads account
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
server/app/services/vuln_scan.py - Vulnerability scanning → OSV vulnerability data: queries vulnerabilities
server/app/services/vuln_scan.py - Vulnerability scanning → Local AI explanations: requests explanations
server/app/services/vuln_scan.py - Local AI explanations → Ollama: uses local model
- SOC dashboard → Attack geolocation: uses attack locations
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
server/app/services/audit.py