> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafter.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI Integration

> Set up Rafter security for OpenAI Codex CLI

# Codex CLI Integration

Rafter provides two skills for [Codex CLI](https://github.com/openai/codex) that add remote code analysis and local security.

## Skills Architecture

<CardGroup cols={2}>
  <Card title="Backend Skill (rafter)" icon="cloud">
    API-based security scanning

    * Trigger remote SAST/SCA scans
    * Retrieve scan results
    * Check usage quota
    * Read-only operations
  </Card>

  <Card title="Local Security Toolkit (rafter-agent-security)" icon="shield">
    Local security operations

    * Secret scanning in files
    * Policy enforcement
    * Extension auditing
    * Audit logging
  </Card>
</CardGroup>

## Setup

### 1. Install Rafter CLI

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @rafter-security/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @rafter-security/cli
  ```

  ```bash pip theme={null}
  pip install rafter-cli
  ```
</CodeGroup>

### 2. Initialize Local Security

```bash theme={null}
rafter agent init --with-codex
```

Rafter detects Codex CLI via `~/.codex` and installs skills to `~/.agents/skills/rafter/`.

To install all detected integrations at once:

```bash theme={null}
rafter agent init --all
```

### 3. Restart Codex CLI

Restart Codex CLI to load the newly installed skills.

## Skill Location

After initialization:

```
~/.agents/skills/
├── rafter/
│   └── SKILL.md              # Remote code analysis skill
└── rafter-agent-security/
    └── SKILL.md              # Local security skill
```

## Usage

### Backend Scanning

Trigger a security scan of your repository:

```bash theme={null}
rafter run --format md
```

Or use the `rafter scan` alias:

```bash theme={null}
rafter scan --repo myorg/myrepo --branch main
```

<Note>Backend scanning requires a [Rafter API key](https://rafter.so). Set it via `export RAFTER_API_KEY="your-key"` or pass `--api-key`.</Note>

### Local Security

These commands work locally without an API key:

```bash theme={null}
# Scan files for secrets
rafter secrets .

# Scan only staged files
rafter secrets --staged

# Execute a command with risk assessment
rafter agent exec "git push --force"

# Audit a third-party skill for malware
rafter agent audit-skill path/to/untrusted-skill.md

# View security event log
rafter agent audit
```

> **Note:** `rafter agent scan` still works but is deprecated — it will be removed in a future major version.

### Skill Auditing

<Warning>
  **Treat third-party extension ecosystems as hostile by default.** There have been reports of malware distributed via skill marketplaces, using social-engineering instructions to run obfuscated shell commands.
</Warning>

Before installing any third-party skill, audit it:

```bash theme={null}
rafter agent audit-skill path/to/untrusted-skill.md
```

This analyzes 12 security dimensions: trust/attribution, network security, command execution, file system access, credential handling, input validation, data exfiltration, obfuscation, scope alignment, error handling, dependencies, and environment manipulation.

## Configuration

### Risk Levels

```bash theme={null}
# Set during init
rafter agent init --risk-level moderate

# Change later
rafter agent config set agent.riskLevel aggressive
```

| Level      | Behavior                                                              |
| ---------- | --------------------------------------------------------------------- |
| Minimal    | Basic guidance, most commands allowed                                 |
| Moderate   | Approval for high-risk commands, secrets always blocked (**default**) |
| Aggressive | Approval for most operations, maximum security                        |

### View Configuration

```bash theme={null}
rafter agent config show
```

## Monitoring

### View Agent Activity

```bash theme={null}
# Recent events (last 10)
rafter agent audit

# Last 50 events
rafter agent audit --last 50

# Filter by event type
rafter agent audit --event secret_detected

# Filter by agent platform
rafter agent audit --agent claude-code
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Skills not loading in Codex CLI">
    1. Verify skills are installed: `ls ~/.agents/skills/rafter/`
    2. Re-run: `rafter agent init --with-codex`
    3. Restart Codex CLI
  </Accordion>

  <Accordion title="Codex CLI not detected during init">
    Ensure `~/.codex` exists, then run: `rafter agent init --with-codex`
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Secret Scanning" icon="key" href="/guides/agent-security/secret-scanning">
    21+ secret patterns detected
  </Card>

  <Card title="Command Execution" icon="terminal" href="/guides/agent-security/command-execution">
    Risk-assessed command validation
  </Card>

  <Card title="Command Reference" icon="book" href="/guides/agent-security/reference">
    Full CLI reference
  </Card>
</CardGroup>