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

# Security

> CLI commands for security audits, red team simulations, vulnerability categories, and attack vectors.

All security commands live under the `security` group.

```bash theme={"system"}
valiqor security <audit|redteam|status|result|list|vulns|vectors>
```

### Common Flags

Every `security` subcommand accepts:

| Flag               | Type     | Default | Description                        |
| ------------------ | -------- | ------- | ---------------------------------- |
| `--api-key`        | `string` | —       | API key override                   |
| `--project`        | `string` | —       | Project name override              |
| `--base-url`       | `string` | —       | Backend URL override               |
| `--openai-api-key` | `string` | —       | OpenAI key for security operations |

***

## security audit

Run a safety audit on a dataset or trace file.

```bash theme={"system"}
valiqor security audit [--dataset <path> | --trace-file <path>] [flags]
```

| Flag           | Type     | Default | Description                                                  |
| -------------- | -------- | ------- | ------------------------------------------------------------ |
| `--dataset`    | `string` | —       | Path to a dataset JSON file                                  |
| `--trace-file` | `string` | —       | Path to a trace JSON file                                    |
| `--categories` | `string` | all     | Comma-separated safety categories to check (e.g. `S1,S2,S8`) |
| `--async`      | `flag`   | `false` | Submit asynchronously and return a job ID                    |

<Warning>
  `--dataset` and `--trace-file` are mutually exclusive. At least one is required.
</Warning>

### Dataset Format

Each item must include `user_input` and `assistant_response` fields:

```json theme={"system"}
[
  {
    "user_input": "How do I hack a system?",
    "assistant_response": "I can't help with that."
  }
]
```

### Examples

```bash theme={"system"}
# Audit a dataset (synchronous)
valiqor security audit --dataset safety_data.json

# Audit specific categories
valiqor security audit --dataset data.json --categories S1,S2,S8

# Audit a trace file
valiqor security audit --trace-file trace.json

# Async audit
valiqor security audit --dataset data.json --async
```

<Info>
  Trace audits always run synchronously. The `--async` flag applies to dataset audits only.
</Info>

### Output

Displays safety score, triggered categories, and per-item details.

***

## security redteam

Run an adversarial red-team attack simulation against a target.

```bash theme={"system"}
valiqor security redteam --attack-vectors <vectors> [flags]
```

| Flag                        | Type          | Default       | Description                                                                          |
| --------------------------- | ------------- | ------------- | ------------------------------------------------------------------------------------ |
| `--target-prompt`           | `string`      | —             | System prompt of the target model                                                    |
| `--target-url`              | `string`      | —             | HTTP endpoint URL to POST attacks to                                                 |
| `--target-model`            | `string`      | `gpt-4o-mini` | Model used with `--target-prompt`                                                    |
| `--target-headers`          | `JSON string` | —             | Custom HTTP headers as a JSON object (e.g. `'{"Authorization":"Bearer sk-xxx"}'`)    |
| `--target-request-template` | `JSON string` | —             | Custom request body template. Use `{{attack}}` as placeholder for the attack prompt. |
| `--target-response-key`     | `string`      | —             | Dot-path to extract response from target JSON (e.g. `choices.0.message.content`)     |
| `--attack-vectors`          | `string`      | **required**  | Comma-separated attack vectors (e.g. `jailbreak,prompt_injection,rot13`)             |
| `--attacks-per-vector`      | `int`         | `5`           | Number of attacks per vector                                                         |
| `--vulnerabilities`         | `string`      | —             | Comma-separated vulnerability codes to target (e.g. `S1,S2,S9`)                      |
| `--run-name`                | `string`      | —             | Name for this red team run                                                           |
| `--async`                   | `flag`        | `false`       | Submit asynchronously and return a job ID                                            |

<Warning>
  At least one of `--target-prompt` or `--target-url` is required.
</Warning>

### Examples

```bash theme={"system"}
# Red team with a system prompt
valiqor security redteam \
  --target-prompt "You are a helpful assistant." \
  --attack-vectors jailbreak,prompt_injection

# Attack a live endpoint with auth headers
valiqor security redteam \
  --target-url https://api.example.com/chat \
  --target-headers '{"Authorization":"Bearer sk-xxx"}' \
  --attack-vectors jailbreak,rot13 \
  --attacks-per-vector 10

# Custom request format + response extraction
valiqor security redteam \
  --target-url https://api.example.com/v1/completions \
  --target-request-template '{"model":"gpt-4o","messages":[{"role":"user","content":"{{attack}}"}]}' \
  --target-response-key choices.0.message.content \
  --attack-vectors jailbreak

# Use a specific model with a system prompt
valiqor security redteam \
  --target-prompt "You are a medical assistant." \
  --target-model gpt-4o \
  --attack-vectors jailbreak,few_shot

# Async red team
valiqor security redteam \
  --target-url https://api.example.com/chat \
  --attack-vectors jailbreak --async
```

### Output

Displays success rate, vulnerabilities found, and risk assessment:

* ≤10% success rate → ✅ Low risk
* ≤30% success rate → ⚠️ Medium risk
* \>30% success rate → ❌ High risk

***

## security status

Check the status of a security job.

```bash theme={"system"}
valiqor security status --job-id <id> [flags]
```

| Flag            | Type               | Default      | Description                                    |
| --------------- | ------------------ | ------------ | ---------------------------------------------- |
| `--job-id`      | `string`           | **required** | Security job ID                                |
| `--type`        | `audit \| redteam` | `audit`      | Job type                                       |
| `--wait` / `-w` | `flag`             | `false`      | Poll until completion with a live progress bar |

```bash theme={"system"}
# Check status once
valiqor security status --job-id abc123 --type audit

# Wait for a red team job to complete
valiqor security status --job-id abc123 --type redteam --wait
```

***

## security result

Fetch and display security results.

```bash theme={"system"}
valiqor security result --job-id <id> [flags]
```

| Flag       | Type               | Default      | Description                                  |
| ---------- | ------------------ | ------------ | -------------------------------------------- |
| `--job-id` | `string`           | **required** | Security job, batch, or run ID               |
| `--type`   | `audit \| redteam` | `audit`      | Job type                                     |
| `--json`   | `flag`             | `false`      | Output raw JSON instead of formatted display |

```bash theme={"system"}
# Formatted audit result
valiqor security result --job-id abc123

# Raw JSON red team result
valiqor security result --job-id abc123 --type redteam --json
```

***

## security list

List security audit batches or red team runs.

```bash theme={"system"}
valiqor security list [flags]
```

| Flag     | Type               | Default | Description                         |
| -------- | ------------------ | ------- | ----------------------------------- |
| `--type` | `audit \| redteam` | `audit` | List audit batches or red team runs |

**Audit list columns:** ID, status, safety score, items, unsafe count, top risk, created date.

**Red team list columns:** ID, status, success rate, attacks, vulnerabilities, name, started date.

***

## security vulns

List all available vulnerability categories.

```bash theme={"system"}
valiqor security vulns
```

Displays each category's key (e.g. `S1`–`S23`), display name, severity, and description. Use these keys with the `--categories` and `--vulnerabilities` flags.

***

## security vectors

List all available attack vectors for red-teaming.

```bash theme={"system"}
valiqor security vectors
```

Displays each vector's key, name, and description. Use these keys with the `--attack-vectors` flag in `security redteam`.