feat(riposte-sextant): push agent readings into the SOC steering file

Sextant counts nothing itself: it receives. Until now the opposite was true — it reached into this SOAR to run a command, which meant SOAR had to host a whitelist table, a screen to fill it, a dedicated permission and a catalogue route. Configuration belonging to another product, living here. As an integration, none of that is needed: an operator creates an instance with a URL and a token like for any other tool, and a scheduled playbook counts on the vendor console, maps, then calls push_agent_stats. The mapping lives in that playbook, which is where it belongs — next to the connector that produced the numbers, and per client rather than per product. WHAT THE SCRIPT REFUSES TO DO, and why it matters more than what it does: a counter left empty is OMITTED, never sent as zero. "We did not measure how many agents are in error" and "no agent is in error" are opposite pieces of news, and the second reassures wrongly — the whole steering file exists not to say it. A counter that is present but not a number is refused instead, naming the field: that is a broken mapping in the calling playbook, and dropping it silently would look exactly like "not measured". Verified against a running Sextant rather than assumed: the deposit files under the paired client with the empty counter absent, a broken mapping is refused by name, and an unpaired client comes back saying which identifier was not recognised. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 08:46:10 +02:00
parent 82f22fdbb3
commit 50358ef8a1
3 changed files with 187 additions and 0 deletions
@@ -0,0 +1,64 @@
+id: riposte-sextant
+name: Riposte Sextant
+version: 1.0.0
+description: >
+  Riposte Sextant — SOC steering. Push what this SOAR already knows about a
+  client's estate into their steering file: agent counters, measured on the
+  vendor console by another command and mapped in the playbook that calls this
+  one. Sextant never connects to anything itself; it receives. Bearer token
+  authentication, stdlib-only, no extra Python dependencies.
+changelog: "1.0.0 — Initial release: push agent counters, and a connection test."
+category: reporting
+
+config_schema:
+  properties:
+    base_url:
+      type: string
+      description: "Sextant's public URL, e.g. https://sextant.example.corp (no trailing path)"
+    token:
+      type: string
+      description: "Ingestion token, created in Sextant under Settings. It writes readings and nothing else: it carries no role and reads nothing."
+      x-soar-sensitive: true
+  required:
+    - base_url
+    - token
+
+commands:
+  - id: push_agent_stats
+    name: sextant-push-agent-stats
+    description: >
+      Deposit one agent reading for a client. Counters left empty stay UNKNOWN in
+      Sextant — never zero: "we did not measure how many agents are in error" and
+      "no agent is in error" are opposite pieces of news, and the second one
+      reassures wrongly. Map only what the console actually returned.
+    # safe_write, and not read: this writes a reading into another product. It
+    # changes nothing on the customer's estate, which is what "safe" means here.
+    risk: safe_write
+    inputs_schema:
+      properties:
+        client_id:
+          type: string
+          description: "The client's id IN THIS SOAR. Sextant resolves its own client through the pairing already recorded on the client sheet — no extra identifier to copy, so none to get wrong."
+        expected:
+          type: number
+          description: "Agents the contract commits to. A commitment, not a measurement — no console knows it. Without it the coverage ratio stays unknown and the raw counters still stand."
+        deployed: { type: number, description: "Agents installed on the estate" }
+        connected: { type: number, description: "Agents talking to the console" }
+        disconnected: { type: number, description: "Agents known but silent" }
+        errored: { type: number, description: "Agents reporting a fault" }
+        outdated: { type: number, description: "Agents running an old version" }
+        unmanaged: { type: number, description: "Machines with no agent" }
+      required: [client_id]
+    outputs_schema:
+      properties:
+        client_id: { type: string, description: "The Sextant client the reading was filed under — the confirmation that the pairing pointed at the right one" }
+        sent: { type: object, description: "The counters actually deposited, so the run log shows what was left unmeasured" }
+
+  - id: test_connection
+    name: sextant-test-connection
+    description: "Check the URL and the ingestion token, without depositing anything."
+    risk: read
+    inputs_schema: { properties: {} }
+    outputs_schema:
+      properties:
+        ok: { type: boolean }