Kairo Documentation

Kairo is an AI-powered smart contract security platform that helps developers identify vulnerabilities and ensure the safety of their Solidity code.

Web Dashboard

Connect your GitHub repositories and scan contracts through our web interface.

CLI Tool

Use the command line interface for local scanning and CI/CD integration.

API Access

Integrate Kairo directly into your applications with our REST API.

Quick Note

This documentation covers the latest version of Kairo. For legacy features or migration guides, please contact our support team.

Quickstart

1. Create an Account

2. Connect Your Repository

Link your GitHub account and select a repository containing Solidity contracts.

bash

# Or clone a sample repository
git clone https://github.com/kairo-ai/sample-contracts
cd sample-contracts

3. Run Your First Scan

Once connected, Kairo will automatically scan your contracts for common vulnerabilities.

✅ Scan completed! View your results in the dashboard to see detected vulnerabilities and recommendations.

Authentication

Kairo uses OAuth for secure authentication with GitHub and other platforms.

GitHub Integration

We use GitHub OAuth to securely access your repositories. No passwords are stored, and you can revoke access anytime.

Read access to public and private repositories
Webhook access for automatic scanning
Organization access (if enabled)

API Keys

For CLI and API access, you'll need an API key. Generate one from your dashboard settings.

bash

# Set your API key as an environment variable
export KAIRO_API_KEY="your-api-key-here"

# Or pass it directly to commands
kairo scan --api-key your-api-key-here contracts/

Core Concepts

Vulnerability Detection

Kairo uses a multi-layered approach to identify security issues in your smart contracts:

Static analysis using pattern matching
AI-powered code analysis
Gas optimization suggestions
Best practice recommendations

Severity Levels

Critical

Security vulnerabilities that could lead to loss of funds

High

Significant issues that should be addressed

Medium

Moderate issues with potential impact

Low

Minor issues and best practice suggestions

Scan Types

Quick Scan

Fast pattern-based analysis for common vulnerabilities. Great for CI/CD integration.

Deep Scan

Comprehensive AI-powered analysis including gas optimization and advanced vulnerability detection.

Supported Chains

Kairo supports Solidity contracts deployed on various EVM-compatible networks:

Ethereum Mainnet

Polygon

BSC

Arbitrum

Optimism

Avalanche

Fantom

Base

Linea

Coming Soon

We're working on adding support for additional chains. Contact us if you need support for a specific network.

CLI Installation

The Kairo CLI provides a powerful command-line interface for scanning contracts locally and integrating with CI/CD pipelines.

npm Installation

bash

npm install -g @kairo/cli

Homebrew (macOS)

bash

brew tap kairo-ai/kairo
brew install kairo

Download Binary

Download the latest release for your platform from GitHub:

Verify Installation

bash

kairo --version

CLI Authentication

Login

bash

kairo auth login

This will open your browser to authenticate with your Kairo account.

Using API Keys

bash

# Set environment variable
export KAIRO_API_KEY="your-api-key"

# Or use the flag
kairo scan --api-key "your-api-key" contracts/

Check Status

bash

kairo auth status

CLI Commands

kairo scan

Scan Solidity contracts for vulnerabilities.

bash

# Scan all contracts in current directory
kairo scan

# Scan specific file
kairo scan contracts/MyContract.sol

# Scan with specific mode
kairo scan --mode deep contracts/

# Output to file
kairo scan --output report.json contracts/

Options:

--mode - Scan mode (quick, deep)
--output - Output file path
--format - Output format (json, sarif, text)
--severity - Minimum severity level

kairo init

Initialize a Kairo configuration file in your project.

bash

kairo init

kairo config

Manage CLI configuration settings.

bash

# View current config
kairo config list

# Set default scan mode
kairo config set scan.mode deep

# Reset config
kairo config reset

CLI Examples

Basic Usage

bash

# Quick scan for CI/CD
kairo scan --mode quick --format sarif --output results.sarif

# Deep scan with detailed output
kairo scan --mode deep --format json contracts/ > audit.json

# Scan only high severity issues
kairo scan --severity high contracts/

GitHub Actions

yaml

name: Security Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install Kairo
        run: npm install -g @kairo/cli

      - name: Run Security Scan
        env:
          KAIRO_API_KEY: ${{ secrets.KAIRO_API_KEY }}
        run: kairo scan --mode quick --format sarif --output audit.sarif

      - name: Upload Results
        uses: github/codeql-action/upload-sarif@v1
        with:
          sarif_file: audit.sarif

Pre-commit Hook

bash

#!/bin/sh
# .git/hooks/pre-commit

echo "Running Kairo security scan..."
kairo scan --mode quick --severity medium

if [ $? -ne 0 ]; then
    echo "Security issues found! Aborting commit."
    exit 1
fi

API Endpoints

The Kairo API provides programmatic access to our security scanning capabilities. All API requests require authentication via API key.

Base URL: https://api.kairo.ai

Authentication: Bearer token in Authorization header

POST /v1/scan

Submit Solidity code for security analysis.

Request

json

{
  "code": "pragma solidity ^0.8.0;\n\ncontract Example {...}",
  "mode": "deep",
  "metadata": {
    "filename": "Example.sol",
    "project": "my-project"
  }
}

Response

json

{
  "scan_id": "scan_123456789",
  "status": "completed",
  "results": {
    "vulnerabilities": [
      {
        "id": "vuln_001",
        "type": "reentrancy",
        "severity": "high",
        "line": 42,
        "description": "Potential reentrancy vulnerability",
        "recommendation": "Use the checks-effects-interactions pattern"
      }
    ],
    "summary": {
      "total": 1,
      "by_severity": {
        "critical": 0,
        "high": 1,
        "medium": 0,
        "low": 0
      }
    }
  }
}

GET /v1/scan/{id}

Retrieve results for a specific scan.

bash

curl -H "Authorization: Bearer your-api-key" \
     https://api.kairo.ai/v1/scan/scan_123456789

GET /v1/scans

List recent scans for your account.

bash

curl -H "Authorization: Bearer your-api-key" \
     "https://api.kairo.ai/v1/scans?limit=10&offset=0"

MCP Server Setup

The Model Context Protocol (MCP) server allows AI assistants to interact directly with Kairo's scanning capabilities.

Installation

bash

npm install -g @kairo/mcp-server

Configuration

Add the following to your MCP client configuration:

json

{
  "mcpServers": {
    "kairo": {
      "command": "npx",
      "args": ["@kairo/mcp-server"],
      "env": {
        "KAIRO_API_KEY": "your-api-key"
      }
    }
  }
}

Available MCP Tools

scan_contract

Scan Solidity contract code for security vulnerabilities.

Parameters: code (string), mode (optional)

get_scan_results

Retrieve detailed results for a previous scan.

Parameters: scan_id (string)

list_scans

List recent scans for the account.

Parameters: limit (optional), project (optional)

Error Handling

HTTP Status Codes

200Success

400Bad Request

401Unauthorized

429Rate Limit Exceeded

500Internal Server Error

Error Response Format

json

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: code",
    "details": {
      "parameter": "code",
      "expected": "string"
    }
  }
}

Rate Limits

API usage is rate-limited based on your subscription plan:

Free Tier

25 scans per month
5 requests per minute
Basic scan mode only

Pro Plan

300 scans per month
60 requests per minute
All scan modes

Enterprise

Unlimited scans
1000 requests per minute
Priority processing

Rate Limit Headers

API responses include rate limit information:

bash

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640995200

Kairo Documentation

Kairo is an AI-powered smart contract security platform that helps developers identify vulnerabilities and ensure the safety of their Solidity code.

Web Dashboard

Connect your GitHub repositories and scan contracts through our web interface.

CLI Tool

Use the command line interface for local scanning and CI/CD integration.

API Access

Integrate Kairo directly into your applications with our REST API.

Quick Note

This documentation covers the latest version of Kairo. For legacy features or migration guides, please contact our support team.

Quickstart

1. Create an Account

2. Connect Your Repository

Link your GitHub account and select a repository containing Solidity contracts.

bash

# Or clone a sample repository
git clone https://github.com/kairo-ai/sample-contracts
cd sample-contracts

3. Run Your First Scan

Once connected, Kairo will automatically scan your contracts for common vulnerabilities.

✅ Scan completed! View your results in the dashboard to see detected vulnerabilities and recommendations.

Authentication

Kairo uses OAuth for secure authentication with GitHub and other platforms.

GitHub Integration

We use GitHub OAuth to securely access your repositories. No passwords are stored, and you can revoke access anytime.

Read access to public and private repositories
Webhook access for automatic scanning
Organization access (if enabled)

API Keys

For CLI and API access, you'll need an API key. Generate one from your dashboard settings.

bash

# Set your API key as an environment variable
export KAIRO_API_KEY="your-api-key-here"

# Or pass it directly to commands
kairo scan --api-key your-api-key-here contracts/

Core Concepts

Vulnerability Detection

Kairo uses a multi-layered approach to identify security issues in your smart contracts:

Static analysis using pattern matching
AI-powered code analysis
Gas optimization suggestions
Best practice recommendations

Severity Levels

Critical

Security vulnerabilities that could lead to loss of funds

High

Significant issues that should be addressed

Medium

Moderate issues with potential impact

Low

Minor issues and best practice suggestions

Scan Types

Quick Scan

Fast pattern-based analysis for common vulnerabilities. Great for CI/CD integration.

Deep Scan

Comprehensive AI-powered analysis including gas optimization and advanced vulnerability detection.

Supported Chains

Kairo supports Solidity contracts deployed on various EVM-compatible networks:

Ethereum Mainnet

Polygon

BSC

Arbitrum

Optimism

Avalanche

Fantom

Base

Linea

Coming Soon

We're working on adding support for additional chains. Contact us if you need support for a specific network.

CLI Installation

The Kairo CLI provides a powerful command-line interface for scanning contracts locally and integrating with CI/CD pipelines.

npm Installation

bash

npm install -g @kairo/cli

Homebrew (macOS)

bash

brew tap kairo-ai/kairo
brew install kairo

Download Binary

Download the latest release for your platform from GitHub:

Verify Installation

bash

kairo --version

CLI Authentication

Login

bash

kairo auth login

This will open your browser to authenticate with your Kairo account.

Using API Keys

bash

# Set environment variable
export KAIRO_API_KEY="your-api-key"

# Or use the flag
kairo scan --api-key "your-api-key" contracts/

Check Status

bash

kairo auth status

CLI Commands

kairo scan

Scan Solidity contracts for vulnerabilities.

bash

# Scan all contracts in current directory
kairo scan

# Scan specific file
kairo scan contracts/MyContract.sol

# Scan with specific mode
kairo scan --mode deep contracts/

# Output to file
kairo scan --output report.json contracts/

Options:

--mode - Scan mode (quick, deep)
--output - Output file path
--format - Output format (json, sarif, text)
--severity - Minimum severity level

kairo init

Initialize a Kairo configuration file in your project.

bash

kairo init

kairo config

Manage CLI configuration settings.

bash

# View current config
kairo config list

# Set default scan mode
kairo config set scan.mode deep

# Reset config
kairo config reset

CLI Examples

Basic Usage

bash

# Quick scan for CI/CD
kairo scan --mode quick --format sarif --output results.sarif

# Deep scan with detailed output
kairo scan --mode deep --format json contracts/ > audit.json

# Scan only high severity issues
kairo scan --severity high contracts/

GitHub Actions

yaml

name: Security Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install Kairo
        run: npm install -g @kairo/cli

      - name: Run Security Scan
        env:
          KAIRO_API_KEY: ${{ secrets.KAIRO_API_KEY }}
        run: kairo scan --mode quick --format sarif --output audit.sarif

      - name: Upload Results
        uses: github/codeql-action/upload-sarif@v1
        with:
          sarif_file: audit.sarif

Pre-commit Hook

bash

#!/bin/sh
# .git/hooks/pre-commit

echo "Running Kairo security scan..."
kairo scan --mode quick --severity medium

if [ $? -ne 0 ]; then
    echo "Security issues found! Aborting commit."
    exit 1
fi

API Endpoints

The Kairo API provides programmatic access to our security scanning capabilities. All API requests require authentication via API key.

Base URL: https://api.kairo.ai

Authentication: Bearer token in Authorization header

POST /v1/scan

Submit Solidity code for security analysis.

Request

json

{
  "code": "pragma solidity ^0.8.0;\n\ncontract Example {...}",
  "mode": "deep",
  "metadata": {
    "filename": "Example.sol",
    "project": "my-project"
  }
}

Response

json

{
  "scan_id": "scan_123456789",
  "status": "completed",
  "results": {
    "vulnerabilities": [
      {
        "id": "vuln_001",
        "type": "reentrancy",
        "severity": "high",
        "line": 42,
        "description": "Potential reentrancy vulnerability",
        "recommendation": "Use the checks-effects-interactions pattern"
      }
    ],
    "summary": {
      "total": 1,
      "by_severity": {
        "critical": 0,
        "high": 1,
        "medium": 0,
        "low": 0
      }
    }
  }
}

GET /v1/scan/{id}

Retrieve results for a specific scan.

bash

curl -H "Authorization: Bearer your-api-key" \
     https://api.kairo.ai/v1/scan/scan_123456789

GET /v1/scans

List recent scans for your account.

bash

curl -H "Authorization: Bearer your-api-key" \
     "https://api.kairo.ai/v1/scans?limit=10&offset=0"

MCP Server Setup

The Model Context Protocol (MCP) server allows AI assistants to interact directly with Kairo's scanning capabilities.

Installation

bash

npm install -g @kairo/mcp-server

Configuration

Add the following to your MCP client configuration:

json

{
  "mcpServers": {
    "kairo": {
      "command": "npx",
      "args": ["@kairo/mcp-server"],
      "env": {
        "KAIRO_API_KEY": "your-api-key"
      }
    }
  }
}

Available MCP Tools

scan_contract

Scan Solidity contract code for security vulnerabilities.

Parameters: code (string), mode (optional)

get_scan_results

Retrieve detailed results for a previous scan.

Parameters: scan_id (string)

list_scans

List recent scans for the account.

Parameters: limit (optional), project (optional)

Error Handling

HTTP Status Codes

200Success

400Bad Request

401Unauthorized

429Rate Limit Exceeded

500Internal Server Error

Error Response Format

json

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: code",
    "details": {
      "parameter": "code",
      "expected": "string"
    }
  }
}

Rate Limits

API usage is rate-limited based on your subscription plan:

Free Tier

25 scans per month
5 requests per minute
Basic scan mode only

Pro Plan

300 scans per month
60 requests per minute
All scan modes

Enterprise

Unlimited scans
1000 requests per minute
Priority processing

Rate Limit Headers

API responses include rate limit information:

bash

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640995200

Kairo Documentation

Web Dashboard

CLI Tool

API Access

Quick Note

Quickstart

1. Create an Account

2. Connect Your Repository

3. Run Your First Scan

Authentication

GitHub Integration

API Keys

Core Concepts

Vulnerability Detection

Severity Levels

Critical

High

Medium

Low

Scan Types

Quick Scan

Deep Scan

Supported Chains

Coming Soon

CLI Installation

npm Installation

Homebrew (macOS)

Download Binary

Verify Installation

CLI Authentication

Login

Using API Keys

Check Status

CLI Commands

kairo scan

Options:

kairo init

kairo config

CLI Examples

Basic Usage

GitHub Actions

Pre-commit Hook

API Endpoints

POST /v1/scan

Request

Response

GET /v1/scan/{id}

GET /v1/scans

MCP Server Setup

Installation

Configuration

Available MCP Tools

scan_contract

get_scan_results

list_scans

Error Handling

HTTP Status Codes

Error Response Format

Rate Limits

Free Tier

Pro Plan

Enterprise

Rate Limit Headers

Ready to Get Started?

Kairo Documentation

Web Dashboard

CLI Tool

API Access

Quick Note

Quickstart

1. Create an Account

2. Connect Your Repository

3. Run Your First Scan

Authentication

GitHub Integration

API Keys

Core Concepts

Vulnerability Detection

Severity Levels

Critical