Documentation

Kairo is an API-first, multi-chain smart contract security platform. It produces decisions (ALLOW / WARN / BLOCK) at critical control points: CI, deploy gates, and post-deployment monitoring. Scan EVM (Solidity) and Solana (Rust/Anchor) projects locally with the CLI, integrate via the API, or use the MCP server with AI coding assistants.

Quickstart

Get Kairo security scanning in your workflow in under 3 minutes.

1. Install the CLI

bash

npm install -g @kairoaisec/cli

2. Authenticate

bash

kairo auth login

Get your API key from your dashboard → Project Settings → API Keys.

3. Scan your contracts

bash

kairo scan ./contracts

4. Check the response

json

{
  "decision": "ALLOW",
  "decision_reason": "No security issues detected. Safe to proceed.",
  "risk_score": 0,
  "summary": { "total": 0, "critical": 0, "high": 0, "medium": 0, "low": 0 }
}

Authentication

All API requests require an API key in the Authorization header.

API Key Format

kairo_sk_live_xxxxx — Production keys

kairo_sk_test_xxxxx — Sandbox keys (coming soon)

Usage

bash

curl -H "Authorization: Bearer kairo_sk_live_xxxxx" ...

Core Concepts

Control Points

Kairo enforces security at four critical control points:

CI/CD

Block unsafe code from merging

Deploy Gate

Final check before mainnet

Monitoring

24/7 surveillance of live contracts

IDE

Real-time feedback (optional)

Decisions

Every API response includes an agentic decision:

Decision	Meaning	CI Action
`ALLOW`	Safe to proceed	Pass
`WARN`	Minor issues, can proceed	Pass (with notes)
`BLOCK`	Critical issues found	Fail
`ESCALATE`	Needs human review	Pending

Supported Chains

Kairo supports smart contract security analysis across multiple chains and languages.

EVM ChainsSolidity

Full support for Ethereum, Polygon, Arbitrum, Optimism, Base, BSC, Avalanche, and any EVM-compatible chain. Integrates with Foundry, Hardhat, Slither, and Mythril.

bash

# Auto-detects Foundry/Hardhat projects
kairo scan ./contracts

SolanaRust / Anchor

Native analysis for Solana programs. Detects missing signer checks, PDA seed collisions, CPI vulnerabilities, account validation flaws, integer overflow, and privilege escalation. Supports Anchor and native Rust programs.

bash

# Auto-detects Anchor projects (Anchor.toml)
kairo scan ./programs --chain solana

Solana Vulnerability Patterns

Missing Signer

Instructions modifying state without signer verification

Account Validation

Missing owner checks, uninitialized accounts, type confusion

PDA Collisions

Seed patterns allowing account substitution or spoofing

CPI Exploits

Unchecked cross-program invocations, arbitrary targets

Arithmetic

Integer overflow/underflow in u64 token calculations

Authority Checks

Missing admin/authority verification on privileged instructions

CLI

Scan smart contracts locally with the Kairo CLI. Code never leaves your environment.

Installation

Requirements

• Node.js 18+ (LTS recommended)
• npm or yarn package manager
• Git (for repository scanning)

Install via npm

bash

npm install -g @kairoaisec/cli

Verify installation

bash

kairo --version

Optional: Slither integration

For enhanced static analysis, install Slither (requires Python 3.8+):

bash

pip install slither-analyzer
# Verify
slither --version

CLI Authentication

Option 1: Browser Login (Recommended)

Opens your browser for secure sign-in. An API key is generated automatically and stored locally.

bash

kairo auth login

Option 2: API Key Login

For CI/CD or headless environments, use an API key directly.

bash

kairo auth login --api-key kairo_sk_live_xxxxx

Option 3: Environment Variable

bash

export KAIRO_API_KEY="kairo_sk_live_xxxxx"
kairo scan ./contracts  # Uses env var automatically

Verify / Logout

bash

kairo auth whoami   # Check current user
kairo auth logout   # Clear credentials

Commands Reference

Authentication

kairo auth login

Authenticate via browser or API key

kairo auth logout

Clear stored credentials

kairo auth whoami

Show current authenticated user

Projects

kairo project list

List all your projects

kairo project create <name>

Create a new project

kairo project select <id>

Set active project for scans

Scanning

kairo scan <path>

Scan Solidity or Solana contracts with full ML pipeline. Auto-detects chain.

kairo scan --fail-on critical

Exit with code 1 if findings match severity (for CI/CD).

kairo scan --format json

Output JSON to stdout (pipe-friendly).

kairo scan --format sarif

Output SARIF for GitHub Code Scanning.

kairo scan --no-upload

Scan locally without cloud sync.

kairo scan --slither-only

Run only Slither analysis.

kairo scan --no-slither

Skip Slither, use Kairo patterns only.

kairo scan --chain solana

Scan Solana/Anchor programs (auto-detected if Anchor.toml present).

Scanning

All scans use the full 6-stage ML security pipeline for maximum accuracy.

Full Security Pipeline

Every scan runs the complete 6-stage analysis: pattern matching (50+ patterns), AST analysis, Solidity version awareness (≥0.8.0), ReentrancyGuard detection, context-aware analysis, and ML pipeline (when authenticated).

bash

kairo scan ./contracts

CI/CD Integration

Use --fail-on to fail builds when vulnerabilities of specified severity are found. Perfect for deployment gates.

bash

kairo scan ./contracts --fail-on critical,high

Piping Output

Use --format json or --format sarif to output structured data.

bash

# Filter critical findings with jq
kairo scan ./contracts --format json | jq '.findings[] | select(.severity == "critical")'

# Generate SARIF for GitHub Code Scanning
kairo scan ./contracts --format sarif > results.sarif

Examples

Basic Scan Workflow

bash

# Install & authenticate
npm install -g @kairoaisec/cli
kairo auth login

# Create or select project
kairo project create "My DeFi Protocol"
kairo project select proj_xyz123

# Scan contracts
kairo scan ./contracts

Solana / Anchor Scan

bash

# Scan an Anchor project
kairo scan ./programs --chain solana

# Auto-detection (if Anchor.toml exists)
cd my-anchor-project
kairo scan .

# Scan with CI/CD gate
kairo scan ./programs --chain solana --fail-on critical,high

# Output JSON for downstream processing
kairo scan ./programs --chain solana --format json | jq '.findings[]'

Pre-commit Hook

bash

# .git/hooks/pre-commit
#!/bin/bash
echo "Running Kairo security scan..."

if kairo scan ./contracts --no-upload --fail-on critical; then
  echo "Security check passed"
else
  echo "Security issues found. Fix before committing."
  exit 1
fi

Troubleshooting

Authentication Failed

Invalid API key or unauthorized

• Check your API key starts with kairo_sk_

• Regenerate key in dashboard if expired

• Ensure you have project access permissions

Scan Failed

No Solidity files found

• Ensure contracts have .sol extension

• Check file path is correct

• Verify contracts directory exists

Slither Not Found

Slither analyzer not installed

• Install with: pip install slither-analyzer

• Or use --no-slither flag to skip

• Requires Python 3.8+

Upload Failed

Network timeout or project not found

• Check internet connection

• Verify project ID with kairo project list

• Use --no-upload for offline scanning

Solana Chain Not Detected

Anchor.toml not found or scanning as EVM

• Use --chain solana flag to explicitly set chain

• Ensure Anchor.toml or Cargo.toml exists in project root

• Check that .rs files are in the programs/ directory

Debug Commands

bash

kairo --version          # Check CLI version
kairo scan . --verbose   # Verbose output
kairo auth whoami        # Authentication status
kairo project list       # Test API connectivity

API

Direct API access for custom integrations and advanced use cases.

Endpoints

POST/v1/analyze

Analyze smart contract code and return a security decision. Supports both Solidity (EVM) and Rust/Anchor (Solana) files.

Request Body (Solidity)

json

{
  "source": {
    "type": "inline",
    "files": [{ "path": "Contract.sol", "content": "..." }]
  },
  "config": {
    "severity_threshold": "high",
    "include_suggestions": true
  }
}

Request Body (Solana)

json

{
  "source": {
    "type": "inline",
    "chain": "solana",
    "files": [{ "path": "lib.rs", "content": "..." }]
  },
  "config": {
    "severity_threshold": "high",
    "include_suggestions": true
  }
}

POST/v1/deploy/check

Final safety check before deployment. Stricter than /analyze.

Request Body

json

{
  "project_id": "proj_xxxxx",
  "contract_name": "Token",
  "network": { "chain_id": 1, "name": "mainnet" }
}

Error Handling

All error responses follow a consistent format.

json

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required. Include Authorization: Bearer <token> header."
  }
}

Status	Code	Description
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	Key valid but lacks permission
`404`	`not_found`	Resource not found
`422`	`validation_error`	Invalid request body or parameters
`429`	`rate_limited`	Too many requests, retry after cooldown

Rate Limits

API requests are rate-limited per API key.

Endpoint	Limit	Window
`/v1/analyze`	60 requests	per minute
`/v1/deploy/check`	30 requests	per minute
`/v1/scans`	120 requests	per minute

Need higher limits? Contact our enterprise team for custom rate limits and SLA guarantees.

MCP Server

Use Kairo with AI coding assistants like Claude Code via the Model Context Protocol.

Setup

The Kairo MCP server lets AI assistants scan contracts, manage projects, and retrieve scan results directly from your editor.

1. Prerequisites

• Node.js 18+
• A Kairo API key
• Claude Code or another MCP-compatible client

2. Add to Claude Code settings

Add the following to your .claude/settings.json or global Claude Code settings:

json

{
  "mcpServers": {
    "kairo": {
      "command": "npx",
      "args": ["tsx", "/path/to/kairo/mcp-server-kairo.ts"],
      "env": {
        "KAIRO_API_KEY": "kairo_sk_live_xxxxx",
        "KAIRO_API_URL": "https://kairoaisec.com/api/v1"
      }
    }
  }
}

3. Verify connection

Once configured, your AI assistant will have access to Kairo tools. Ask it to "list my Kairo projects" or "scan this contract for vulnerabilities" to verify the connection.

Available Tools

The MCP server exposes the following tools to AI assistants:

analyze_contract

Analyze inline Solidity code for vulnerabilities.

Params: code, name (optional)

scan_file

Scan a single .sol file by path or inline code with full ML pipeline.

Params: path or code

scan_project

Scan an entire project directory (Foundry/Hardhat). Optionally include Slither.

Params: path, skipTests, skipDeps, slither, upload, projectId

detect_project

Detect project type and structure (Foundry, Hardhat, etc.).

Params: path

list_projects

List all projects in your Kairo account.

Params: (none)

create_project

Create a new project.

Params: name, description (optional)

deploy_safety_check

Check deployment safety for contract bytecode.

Params: bytecode, network (optional)

list_scans

List scan history, optionally filtered by project.

Params: projectId (optional), limit (optional)

get_scan_results

Get detailed results from a previous scan.

Params: scanId

generate_report

Generate a security report (PDF, JSON, HTML).

Params: scanId, format

create_pr_with_findings

Create a GitHub PR with security findings as comments.

Params: scanId, repo, branch, baseBranch, title

Configuration

Environment Variables

Variable	Required	Description
`KAIRO_API_KEY`	Yes	Your Kairo API key
`KAIRO_API_URL`	No	API base URL (defaults to localhost:3000)

Running Standalone

You can also run the MCP server directly for testing:

bash

KAIRO_API_KEY=kairo_sk_live_xxxxx npx tsx mcp-server-kairo.ts

Integrations

Plug Kairo into your existing development workflow.

CI/CD

Add Kairo security scanning to your GitHub Actions workflow. Choose from three scan modes that balance speed and depth.

Scan Modes

fastPattern analysis + Slither. Runs locally in <5 seconds. Great for every push.

deepAI + ML + dynamic testing via Kairo backend. 1-2 minutes. Default for PRs.

pentestFull adversarial analysis with fuzzing, exploit generation, and fork testing. 3-10 minutes. Trigger on-demand via PR label.

Basic Setup (Deep Mode)

yaml

# .github/workflows/security.yml
name: Kairo Security
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
    types: [opened, synchronize, labeled]

permissions:
  contents: read
  security-events: write
  pull-requests: write

jobs:
  kairo-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Kairo Security Scan
        uses: kairoaisec/kairo-action@v1
        with:
          api-key: ${{ secrets.KAIRO_API_KEY }}
          path: ./contracts
          mode: deep
          fail-on: critical,high

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: kairo-results.sarif

Deep and pentest modes run asynchronously on the Kairo backend, so they never time out. The action submits the scan, polls for completion, and posts results as a PR comment with attack graphs and exploitability data.

Pentest Mode

Run full adversarial penetration testing on your smart contracts. Pentest mode includes everything in deep mode plus fuzzing (Medusa), AI-generated exploit contracts, and fork testing.

Trigger via PR Label (Recommended)

Add the kairo-pentest label to any PR to automatically upgrade the scan to pentest mode.

yaml

# Default deep scan, pentest when labeled
- name: Kairo Security Scan
  uses: kairoaisec/kairo-action@v1
  with:
    api-key: ${{ secrets.KAIRO_API_KEY }}
    path: ./contracts
    mode: deep  # Automatically upgrades to pentest if PR has 'kairo-pentest' label

Configure via .kairo.yml

Add a .kairo.yml file to your repository root for fine-grained control.

yaml

# .kairo.yml
mode: deep
fail_on: critical,high

# Auto-pentest PRs targeting these branches
pentest_branches:
  - main
  - master
  - release/*

# Paths to scan (default: ./contracts)
paths:
  - contracts/
  - src/

PR Comment Output

After a deep or pentest scan completes, Kairo posts a rich PR comment including:

• Risk score with pass/fail decision
• Severity breakdown (critical, high, medium, low)
• Exploitability matrix — confirmed, unverified, not-exploitable counts
• Mermaid attack flow graph rendered natively by GitHub
• Severity distribution pie chart
• Collapsible exploit PoCs and fuzz crash inputs
• Inline code annotations on affected lines

GitHub Code Scanning

Generate SARIF reports to see vulnerabilities in PR diffs and the GitHub Security tab.

CLI SARIF Generation

bash

# Generate SARIF report
kairo scan ./contracts --sarif results.sarif

# Generate only SARIF (no terminal output)
kairo scan ./contracts --sarif-only --sarif results.sarif

Benefits

• See vulnerabilities inline in PR diffs
• Native GitHub Security tab integration
• Centralized security dashboard
• Industry-standard SARIF 2.1.0 format
• Works with GitHub Advanced Security

Deploy Gate

Add a final safety check before mainnet deployment.

javascript

// deploy.js
async function deploy() {
  // 1. Compile contract
  const compiled = await compile();

  // 2. Check with Kairo before deploying
  const check = await fetch('https://kairoaisec.com/api/v1/deploy/check', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.KAIRO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      project_id: process.env.KAIRO_PROJECT_ID,
      contract_name: 'Treasury',
      network: { chain_id: 1, name: 'mainnet' },
    }),
  }).then(r => r.json());

  if (check.decision === 'BLOCK') {
    console.error('Deployment blocked:', check.decision_reason);
    process.exit(1);
  }

  // 3. Proceed with deployment
  const tx = await deployer.deploy(compiled);
  console.log('Deployed:', tx.hash);
}

IDE

The Kairo IDE provides an optional browser-based environment with real-time security feedback during development.

Features

• Real-time vulnerability highlighting
• AI-powered auto-fix suggestions
• Pre-deployment safety gate
• Integrated test execution

The IDE is not required for API access. Teams can use the API directly via CI/CD, deploy scripts, or custom tooling.

Need Help?

Questions about integration or API usage?