siriusscan--sirius/documentation/dev/architecture/README.auth-surface-matrix.md

title, description, template, llm_context, categories, tags, related_docs

title	description	template	llm_context	categories	tags	related_docs
Auth Surface Matrix	Authoritative authentication and operation policy matrix for all Sirius API surfaces.	TEMPLATE.reference	high	architecture security operations	auth apikey trpc valkey rabbitmq agent	README.architecture.md README.development.md README.container-testing.md README.tasks.md

Auth Surface Matrix

This checklist is the canonical auth policy map for current Sirius architecture.

Current Auth Model

• UI user auth: NextAuth session -> protectedProcedure in tRPC.
• Service auth: X-API-Key -> Go API middleware validation.
• Agent auth: gRPC token model for agent channel identity.
• Current platform model: single UI admin (no multi-user tenant isolation yet).

Architecture Decision: Startup and Secret Strategy

Decision Summary

• Startup onboarding is installer-first: generate/merge runtime config before compose startup.
• The infrastructure/root API key is validated statelessly from environment configuration.
• Valkey-backed key validation remains for dynamic, user-generated API keys only.
• Runtime auth and seed flows fail fast when required secrets are missing in production.

Rationale

• Removes bootstrap drift between persistent key-value state and deployment configuration.
• Reduces first-run friction by automating secret generation and synchronization.
• Improves operational reliability for key rotation and service restarts.
• Aligns local and automated deployments with a single deterministic configuration model.

Operational Implications

• Health endpoints remain public by explicit policy.
• Non-health API endpoints require X-API-Key and validate against either:
  • environment root key (infrastructure path), or
  • Valkey metadata (dynamic key path).
• Migration guidance is required for users moving from manual .env setup to installer flow.

Policy Checklist

• All sensitive tRPC procedures require protectedProcedure.
• Go API middleware enforces API key for non-health routes.
• UI -> Go API calls use shared authenticated client (apiClient / apiFetch).
• Direct tRPC backends (Valkey/RabbitMQ) remain session-gated.
• Agent identity to HTTP/API actions is fully cryptographically bound.
• Production key lifecycle is deterministic for root key validation and user-key lifecycle handling.

tRPC Procedure Matrix (By Router)

Each row captures backend target and operation class.

Router	Procedures	Backend Target	Operation Class	Required Auth
apikeys	createKey, listKeys, revokeKey	Go API /api/v1/keys*	Read/Write/Delete	Session + API key
host	createHost, getHostList, updateHost, getHost, getHostStatistics, getEnvironmentSummary, getAllHosts, getSourceCoverage, getHostWithSources, getHostSoftwareInventory, getHostSoftwareStats, getHostSystemFingerprint, getEnhancedHostData, getEnvironmentSoftwareStats, getHostTemplateResults, getEnvironmentSoftwareInventory, getHostHistory, getVulnerabilityHistory	Go API /host*	Read/Write	Session + API key
vulnerability	addVulnerabilityToHost, getVulnerability, getAffectedHosts, getSoftwareDescription, getAllVulnerabilities	Go API + external wiki lookup	Read/Write	Session (+ API key for Go API calls)
scanner	getLatestScan, startScan, getScanStatus, cancelScan, forceStopScan, resetScanState	mixed (local + Go API /api/v1/scans*)	Read/Write	Session (+ API key for Go API calls)
templates	getTemplates, getTemplate, createTemplate, updateTemplate, deleteTemplate	Go API /templates* via apiFetch	Read/Write/Delete	Session + API key
scripts	getScripts, getScript, createScript, updateScript, deleteScript	Go API /scripts* via apiFetch	Read/Write/Delete	Session + API key
agentTemplates	getTemplates, getTemplate, uploadTemplate, validateTemplate, updateTemplate, deleteTemplate, testTemplate, deployTemplate, getAnalytics, getTemplateResults	Go API /api/agent-templates*	Read/Write/Delete/Exec	Session + API key
repositories	list, add, update, delete, sync, getSyncStatus	Go API /api/agent-templates/repositories*	Read/Write/Delete	Session + API key
events	getEvents, getEventStats, getRecentEvents, getEventsBySeverity	Go API /api/v1/events*	Read	Session + API key
statistics	createSnapshot, getVulnerabilityTrends, listSnapshots, getMostVulnerableHosts	Go API /api/v1/statistics*	Read/Write	Session + API key
logs	list, stats	Go API /api/v1/logs* via apiFetch	Read	Session + internal API key (server-side only)
store	initializeNseScripts, getValue, setValue, getNseScripts, getNseScript, updateNseScript, createNseScript, deleteNseScript, getNseRepositories, addNseRepository, removeNseRepository, initializeNseRepositories	Direct Valkey	Read/Write/Delete	Session
queue	sendMsg	Direct RabbitMQ	Write/Exec	Session
agent	listAgentsWithHosts, getAgentDetails, getTemplates, discoverTemplates, getTemplatesFromValKey, discoverTemplatesFromValKey, getTemplateContent, getScriptsFromValKey, discoverScriptsFromValKey, getScriptContent	RabbitMQ + Go API + Valkey	Read/Exec	Session
agentScan	dispatchAgentScan, getAgentScanStatus	RabbitMQ + Valkey	Write/Read	Session
terminal	executeCommand, getHistory, addHistoryEntry, deleteHistoryEntry, clearHistory	RabbitMQ + Valkey	Exec/Read/Write/Delete	Session
user	updateProfile, changePassword, getProfile	Prisma DB	Read/Write	Session
example	hello, getAll, getSecretMessage	local/prisma demo	mixed	mixed (demo only)

Go API Endpoint Matrix (By Route Group)

All routes are under API key middleware except explicit health bypass.

Group	Paths	Operation Class	Required Auth
health	/health	Read	Public (intentional)
system	/api/v1/system/health, /api/v1/system/logs, /api/v1/system/resources	Read	API key
admin	/api/v1/admin/command	Exec	API key
logs	/api/v1/logs, /api/v1/logs/stats, /api/v1/logs/clear, /api/v1/logs/:logId	Read/Write/Delete	Internal service API key (SIRIUS_API_KEY_FILE preferred, SIRIUS_API_KEY fallback). Browser UI uses tRPC logs router (session), not direct calls.
host	/host/*, /vulnerability/:id/sources	Read/Write/Delete	API key
vulnerability	/vulnerability/:id, /vulnerability/, /vulnerability/delete	Read/Write/Delete	API key
template	/templates/*	Read/Write/Delete	API key
agent template	/api/agent-templates/*	Read/Write/Delete/Exec	API key
repository	/api/agent-templates/repositories/*	Read/Write/Delete	API key
events	/api/v1/events/*	Read	API key
statistics	/api/v1/statistics/*	Read/Write	API key
scan control	/api/v1/scans/*	Read/Write	API key
api key mgmt	/api/v1/keys/*	Read/Write/Delete	API key
app passthrough	/app/:appName	Write/Exec	API key

Agent and NHI Boundary Matrix

Boundary	Identity Mechanism	Current State	Required Control
Agent -> Engine (gRPC)	Agent token in stream messages	implemented	keep enforced
Engine/Agent -> Go API (HTTP)	Internal service key (file or env)	normalized via shared loader / logging client patch	keep X-API-Key on all internal HTTP clients
UI admin -> Agent dispatch	Session-gated tRPC + queue payloads	implemented but trust of client-supplied agent IDs needs hardening	validate agent existence/state on dispatch
Agent metadata ingestion	host source metadata	accepted from clients	validate schema and origin coupling

IDOR Opportunity Review (Current Stage)

Given single-admin model, current focus is authn + object selector hardening:

• selectors to validate consistently: id, ip, vulnId, scanId, templateId, agentId.
• malformed selectors should fail fast with 400.
• non-existent resources should return 404.
• unauthorized/unauthenticated should return 401 (and 403 when explicit deny model is later introduced).

Verification Hooks

• Security harness must cover:
  • Go API authn enforcement for all route families.
  • tRPC session enforcement for all non-demo routers.
  • direct Valkey/RabbitMQ procedure access controls.
  • agent misuse cases (invalid/stale/mismatched agent IDs).