# CISO360AI API

> REST API + MCP server for the CISO360AI cybersecurity management platform, operated by alterSec Limited (NZBN 9429047827035, New Zealand). This service is the FastAPI backend that powers the web app at https://app.ciso360.ai. It is multi-tenant: every authenticated request is bound to an org (and usually a project) via the JWT or API key. The MCP server derives your organisation from your API key, and you choose project scope per call.

The platform is currently offered in PREVIEW. The API is provided as-is, with no warranty and no liability for preview/free-tier use. See the Terms of Service for the full posture.

## Integration — recommended path

- **AI agents → MCP server (recommended).** Connect any MCP client to `https://api.ciso360.ai/mcp` (streamable HTTP) with a scoped API key (`Authorization: Bearer csk_...`) or OAuth 2.1 with Dynamic Client Registration (DCR); your organisation is derived from the credential. See the MCP section below for tools, project scope, and approvals.
- **Scripts / M2M → REST API + scoped API key (secondary).** Use the OpenAPI endpoints below with an `Authorization: Bearer csk_...` key, issued per user and bound to one organisation.

## Interactive documentation

- [Swagger UI](/api/docs): interactive OpenAPI 3 explorer for every endpoint, with request/response schemas and try-it-out.
- [ReDoc](/api/redoc): static reference rendering of the same OpenAPI document.
- [openapi.json](/api/openapi.json): machine-readable OpenAPI 3 schema — feed this to a code generator or LLM to derive a typed client.

## Authentication

- **Web sessions**: OIDC with PKCE (RFC 7636) → NextAuth → JWT bearer.
- **M2M / scripts / MCP / agents**: user-managed API keys (`csk_...`), opaque tokens issued per user and bound to one org. Send as an `Authorization: Bearer csk_...` header. See the `api-keys` group in [Swagger](/api/docs).
- All endpoints validate the JWT (or API key) and enforce tenant isolation via per-tenant namespace/database scoping. Cross-org access via API key is rejected as a defence-in-depth measure.

## MCP (Model Context Protocol)

Connect your own agent — Claude, GitHub Copilot, ChatGPT, Microsoft Copilot, Cursor, or any MCP client — directly to CISO360AI. The MCP server speaks streamable HTTP and authenticates with a Client Secret Key; your organisation is derived from the key, so no org or project appears in the URL.

- **Endpoint**: `https://api.ciso360.ai/mcp` (streamable HTTP).
- **Auth**: an API key (`Authorization: Bearer csk_...`) from Settings → API Keys — prefer an agent key with the narrowest scopes — or OAuth 2.1 with Dynamic Client Registration (DCR). Your organisation is derived from the credential.
- **Project scope**: read tools return every project in your organisation by default, each result tagged with its project; pass an optional `project_id` argument to scope to one. Write tools require an explicit `project_id` (no silent cross-project writes). Call `list_projects` first to discover project ids. One agent can operate across a whole multi-project programme; MSPs/MSSPs and vCISOs use a scoped key (or OAuth across your organisations) per organisation, with project sharing for third-party assessments.
- **Approvals**: destructive actions and risk-acceptance require a human-approval step in the app; lower-risk triage (marking a finding `false_positive` or `suppressed`) executes autonomously and is recorded in the audit log. Agent keys are deny-by-default and can never run destructive tools.

Example client configuration (any MCP-compatible client):

```json
{ "type": "http", "url": "https://api.ciso360.ai/mcp", "headers": { "Authorization": "Bearer csk_..." } }
```

The authoritative tool list and JSON schemas are discoverable at runtime via the MCP `tools/list` method once connected.

### MCP read tools
`list_projects`, `get_context`, `get_asset`, `list_assets`, `list_findings`, `list_vulnerabilities`, `get_cve_detail`, `list_identity_findings`, `get_project_summary`, `read_org_preferences`, `list_risks`, `list_actions`, `list_controls`, `get_risk_stats`, `list_frameworks` (NIST CSF v2.0, NCSC MCSS, NZ HISF, CIS Controls v8.1, custom), `list_assessments`, `list_requirements`, `get_requirement`, `get_assessment`, `get_coverage`, `get_maturity`, `get_gaps`, `list_findings_for_requirement`.

### MCP propose-and-approve tools (write, gated)
`propose_score`, `propose_mapping`, `propose_remediation`, `propose_state_validation`, `propose_evidence_link`, `propose_remediation_plan`, `run_assessment_workflow`, `delete_asset`.

### MCP vulnerability-triage tools (write)
- `triage_finding` — set a single finding's status to `false_positive`, `suppressed`, or `accepted` with a required reason; accepts an optional `suppress_until` (ISO-8601 datetime) for time-bound suppression. `accepted` is approval-gated; `false_positive`/`suppressed` execute autonomously.
- `bulk_triage_findings` — apply one triage verdict (and optional `suppress_until`) to up to 100 findings in a single call.
- `link_finding_to_risk` — link a finding to a manually-created risk on the risk registry; executes autonomously.

## Health & observability

- `GET /` — API info (version, docs URL, status).
- `GET /health` — liveness probe.
- `GET /health/temporal` — Temporal worker liveness probe (status + worker counts; 503 when degraded/unreachable).

## Core endpoint groups (full list in Swagger)

- `auth` — current user, org/project context, API context for scripts.
- `organizations` / `project` — tenant primitives.
- `assets`, `findings`, `vulnerabilities`, `identity-exposures` — security data plane, including dark-web identity/credential exposures.
- `scans`, `events`, `event-assets`, `domains` — scan lifecycle, event stream, and domain-ownership verification for identity scans.
- `compliance` — frameworks, requirements, assessments, derivations, and the risk register.
- `chat` — AI Sidekick conversations (LLM-backed, MCP-aware).
- `api-keys`, `subscription`, `notifications`, `provenance`, `graph`, `relationships`, `generic-entities`.

## Legal & policy

- [Terms of Service](https://ciso360.ai/legal/terms): governing terms — preview status, AS-IS, no-warranty, no-liability for preview/free tier, AI-output verification clause, authorisation-to-scan warranty.
- [Privacy Policy](https://ciso360.ai/legal/privacy): personal data handling under GDPR and equivalent regimes.
- [Security Policy / Vulnerability Disclosure](https://ciso360.ai/legal/security): in-scope assets, reporting expectations, acknowledgement timelines.
- [security.txt](https://app.ciso360.ai/.well-known/security.txt): machine-readable security contact (RFC 9116).

## Optional

- [Marketing site](https://ciso360.ai/): product overview, pricing, standards and roadmap; serves [/llms.txt](https://ciso360.ai/llms.txt) — the product-level discovery index.
- [Web app](https://app.ciso360.ai/): the authenticated product surface (noindex).