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 }