REST API

The Obexum portal exposes a versioned REST API at https://obexum.com/api/v1/ for automation, CI integrations, and SIEM/TIP ingestion. All endpoints use cookie session auth (when called from a browser) or bearer-token auth (for machine clients).

Authentication

Issue API tokens from /app/settings/api-tokens (logged in) or via the dashboard UI. Tokens are 32 random bytes, base64url-encoded with prefix obxk_.

Issue a token (cookie auth)

curl -X POST https://obexum.com/app/settings/api-tokens \
  -H "Cookie: obx_session=<your session>" \
  -d "name=ci-pipeline" \
  -d "scope=read:findings" \
  -d "scope=write:scans" \
  -d "expires_days=90"

{
  "token": {
    "id": "...",
    "user_id": "...",
    "name": "ci-pipeline",
    "prefix": "obxk_abc12345",
    "scopes": ["read:findings","write:scans"],
    "expires_at": "2026-08-10T..."
  },
  "plaintext": "obxk_abc12345DEFghi...",
  "warning": "Store this token immediately — it is shown only once."
}

Use a token

curl https://obexum.com/api/v1/engagements \
  -H "Authorization: Bearer obxk_abc12345DEFghi..."

Endpoints

Engagements

List engagements owned by the authenticated user.

Findings

List findings for an engagement. Filters: ?status=open, ?severity=critical.

Aggregated counts by severity / status / category.

Reports

Structured JSON snapshot of all findings, frameworks, remediation guidance, and scan integrity chain.

Pericial-grade PDF report. Signed with HMAC-SHA256 (signature in X-Obexum-Report-Signature header).

STIX 2.1 bundle for SIEM/TIP ingestion. Vulnerability SDOs + attack-pattern SDOs + relationship objects linking findings → CVEs → MITRE ATT&CK techniques.

Scan upload

Upload a scan JSON payload (output of obexum scan). Triggers re-evaluation against latest CVE feed + fires configured SIEM webhook.

STIX 2.1 export

Each scan finding is exported as a custom x-obexum-finding SDO. References to CVEs become vulnerability SDOs; MITRE ATT&CK techniques become attack-pattern SDOs. Relationships are typed (exposes for finding→CVE, uses for finding→technique).

{
  "type": "bundle",
  "id": "bundle--...",
  "spec_version": "2.1",
  "objects": [
    {
      "type": "x-obexum-finding",
      "spec_version": "2.1",
      "id": "x-obexum-finding--...",
      "name": "Tamper Protection disabled",
      "severity": "high",
      "status": "open",
      "rule_id": "WIN-DEF-002",
      "x_obexum_remediation": {
        "commands": ["Set-MpPreference -DisableTamperProtection $false"],
        "verification": "Get-MpPreference | Select-Object -ExpandProperty IsTamperProtected",
        "risk_of_fix": "low"
      }
    },
    {
      "type": "attack-pattern",
      "id": "attack-pattern--...",
      "name": "T1562.001"
    },
    {
      "type": "relationship",
      "relationship_type": "uses",
      "source_ref": "x-obexum-finding--...",
      "target_ref": "attack-pattern--..."
    }
  ]
}

SIEM webhooks

Configure a webhook URL per engagement. On scan upload, the portal POSTs the findings payload to your endpoint async (timeout 30s; failures logged, never block ingest).

Supported formats

• generic — native Obexum JSON; verify via X-Obexum-Signature: sha256=<hex> HMAC header
• splunk_hec — Splunk HTTP Event Collector (sets Authorization: Splunk <token>)
• sentinel — Microsoft Sentinel Data Collector compatible
• elastic — Elastic Beats compatible (@timestamp + event_type fields)

Signature verification

# Python
import hmac, hashlib
expected = hmac.new(secret, request.body, hashlib.sha256).hexdigest()
received = request.headers["X-Obexum-Signature"].removeprefix("sha256=")
assert hmac.compare_digest(expected, received)

Rate limits

Default: 60 requests per minute per token, sliding window. Exceeding returns HTTP 429 with Retry-After: 60. Headers on every response:

• X-RateLimit-Limit: 60
• X-RateLimit-Remaining: <n>

Versioning & deprecation

Breaking changes increment the major version (/api/v2/). Old versions remain available for 12 months after a successor ships. Deprecations announced in changelog + Retry-After header.