@xorasecurity/cli

The Xora CLI runs an exploit-validation against a deployed pre-prod environment registered in the Xora dashboard. It's the binary the CI Integrations page snippet points at.

Install

npm install -g @xorasecurity/cli

Or zero-install for a single CI run:

npx @xorasecurity/cli validate --application your-app-slug --env staging --block-on-exploit

Pin a major version (@xorasecurity/cli@1) in CI snippets so patches roll in but breaking-change majors don't.

Auth

Get an API key from /api-keys and store it once per machine:

xora auth login --api-key <key>
xora auth login --api-key <key> --check   # also verify it works

In CI, set XORA_API_KEY as a repo or org secret — the env var shadows the stored file.

Commands

xora validate

Submits a run, streams logs, and exits with the right code.

xora validate --application your-app-slug --env staging --block-on-exploit

Flags:

| Flag | Description | |---|---| | --application <slug> | Required. Application slug from the dashboard. | | --env <name> | Required. Environment name registered for that application. | | --block-on-exploit | Exit 1 when the run completes with exploits. | | --pr <number> | Associate the run with a PR (auto-detected on GH Actions). | | --config <path> | Explicit xora.config.json path. | | -C, --cwd <dir> | Project root. | | --force-project-map | Regenerate .xora/project-map.json. |

Both required flags can be supplied via xora.config.json's defaultApplication / defaultEnv keys instead of the command line.

Exit codes:

• 0 — clean run (or exploits found without --block-on-exploit).
• 1 — exploits found with --block-on-exploit, or scan failed.
• 2 — CLI-side error (bad flag, no API key, network/config error).

xora whoami

Prints the org + API-key label the stored credentials resolve to. Useful as a fail-fast probe before a long CI step.

$ xora whoami
org:   acme  (Acme Inc.)
key:   ci-default  [read_write]

xora auth login / xora auth logout

Manage stored credentials. Stored at ~/.config/xora/credentials.json with mode 0600.

MCP server (editor integration)

xora mcp runs a read-only MCP server over stdio, exposing your Xora findings to agentic editors.

Claude Code — one command:

claude mcp add xora --env XORA_API_KEY=<your key> -- npx -y @xorasecurity/cli mcp

Add --scope user to enable it in every project, or --scope project to write a shared .mcp.json your teammates pick up. Run it from the repo you scan, then ask Claude e.g. "what security findings does Xora have for this repo?" (/mcp shows connection status).

Cursor / manual config — add to .cursor/mcp.json or .mcp.json:

{
  "mcpServers": {
    "xora": {
      "command": "npx",
      "args": ["-y", "@xorasecurity/cli", "mcp"],
      "env": { "XORA_API_KEY": "<your key>" }
    }
  }
}

With the CLI installed globally, "command": "xora", "args": ["mcp"] also works, and a key stored via xora auth login makes the env block unnecessary in either setup. The server detects the workspace's git remote and scopes list_findings to that repository by default — every response carries a filter_context stating the applied scope, filtering by application slug suppresses the workspace default, and a workspace default that matches nothing automatically widens to org-wide (labeled in the response). A read-scope key is sufficient. Tools: list_findings (filter by repo, application slug, severity, state, exploitability), get_finding (full detail: vulnerable code, exploit evidence, chains, artifacts, remediation and fix-PR link).

xora.config.json

Optional config file at the repo root. Lookup precedence (highest first): --config <path>, XORA_CONFIG env var, xora.config.json walked up to the repo root.

{
  "defaultEnv": "staging",
  "defaultApplication": "acme-app",
  "stack": {
    "framework": "nextjs"
  }
}

stack is a partial override — any field you set wins over detection; any field you leave out falls back to the auto-detected value.

CI

The canonical GitHub Actions snippet — drop it into your repo as .github/workflows/xora.yml (or paste it from the dashboard):

name: Xora exploit validation
on:
  workflow_run:
    workflows: ["Deploy to staging"]
    types: [completed]
jobs:
  xora:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @xorasecurity/cli@1
      - run: xora validate --application your-app-slug --env staging --block-on-exploit
        env:
          XORA_API_KEY: ${{ secrets.XORA_API_KEY }}

The trigger is workflow_run chained off your deploy workflow because Xora attacks the deployed environment — not the PR source. Replace "Deploy to staging" with the name of your own deploy workflow.

Environment variables

| Var | Purpose | |---|---| | XORA_API_KEY | API key (shadows stored credentials file). | | XORA_API_BASE_URL | Override API origin (defaults to https://app.getxora.ai). | | XORA_CONFIG | Path to xora.config.json. | | NO_COLOR | Suppress ANSI colors. | | FORCE_COLOR | Force ANSI colors even in non-TTY. |

License

UNLICENSED — proprietary, distributed for use with the Xora service.