14 lines
3.3 KiB
Plaintext
14 lines
3.3 KiB
Plaintext
Project Sentinel: API Gateway & Headless AccessVersion: 3.0.0-EnterpriseModule: 42-Integration-APIMaps to: cmd/sentinel/server/Scope: REST and gRPC interfaces for programmatic control, dashboard integration, and CI/CD automation.1. The Sentinel Control PlaneWhile the MCP interface is designed for LLMs, the REST API is designed for deterministic systems (CI pipelines, Dashboards, Scripts).Sentinel exposes a local HTTP server when run with sentinel serve --http=:8080.1.1 AuthenticationSince Sentinel runs locally, auth is handled via Localhost Binding or API Tokens (for remote/shared instances).Header: X-Sentinel-Token: <generated-token>Token Location: Stored in .sentinel/config/auth (User readable only).2. API Reference (OpenAPI/Swagger)Sentinel auto-generates its Swagger spec at GET /swagger.json.2.1 Sprint Management EndpointsGET /v1/sprint/currentReturns: JSON object of the active sprint, start time, and aggregate metrics.POST /v1/sprint/{id}/archivePayload: { "retro_notes": "...", "force": false }Effect: Triggers the archive_sprint workflow programmatically.2.2 Task OperationsGET /v1/tasks?status=in_progressPOST /v1/tasksPayload: { "title": "Fix Bug", "complexity": "S" }Effect: Inserts task into SQLite and returns the generated ID (T-105).2.3 Policy & CompliancePOST /v1/policy/checkPayload: { "file_path": "src/auth.go", "content": "..." }Effect: Runs the "Virtual File System Jail" and "Static Analysis" logic on the provided content without writing to disk.Use Case: Pre-commit hooks can send the staged file content here to verify compliance before git commit.3. Webhooks & EventsSentinel supports an event-driven architecture via Webhooks.3.1 Event SubscriptionsYou can configure sentinel.toml to POST events to an external URL (e.g., Slack, Discord, or an internal metric collector).[webhooks]
|
|
url = "[https://hooks.slack.com/services/](https://hooks.slack.com/services/)..."
|
|
events = ["sprint.start", "security.violation", "task.done"]
|
|
3.2 Payload Format{
|
|
"event": "security.violation",
|
|
"timestamp": "2026-01-18T10:00:00Z",
|
|
"agent_id": "claude-3.5",
|
|
"data": {
|
|
"rule": "no_env_edit",
|
|
"target": ".env",
|
|
"attempted_action": "write"
|
|
}
|
|
}
|
|
4. The gRPC InterfaceFor high-performance integrations (e.g., streaming logs to a dashboard), Sentinel exposes a gRPC port (Default: :50051).4.1 Log StreamingService: LogStreamMethod: Subscribe(Filter)Behavior: Streams AuditLogEntry objects in real-time as the Agent operates. This allows a "Live View" dashboard to show exactly what the Agent is doing with millisecond latency.4.2 Remote Execution (Advanced)Service: ExecutorMethod: ExecTool(ToolRequest)Security: Requires Mutual TLS (mTLS). This allows a central "Sentinel Controller" to orchestrate agents running on distributed nodes.5. Integration Scenarios5.1 The "Backstage" Developer PortalCompanies using Backstage.io can use the Sentinel API to visualize Agent activity.Plugin: backstage-plugin-sentinelFunction:Fetches /v1/sprint/current to show widget on user homepage.Fetches /v1/audit/stats to show "Safety Score" of the repository.5.2 CI/CD TriggeringScenario: GitHub Action triggers a Sentinel Audit.Implementation:The Action spins up sentinel serve.The Action uses curl to POST the PR diff to /v1/policy/check.If the API returns 403 Forbidden, the Action fails the build. |