# Culebra Documentation
Complete reference for Culebra -- compiler diagnostics and template-driven pattern scanning for LLVM IR.
---
## Table of Contents
- [Installation](#installation)
- [Commands Reference](#commands-reference)
- [scan](#scan)
- [templates](#templates)
- [workflow](#workflow)
- [strings](#strings)
- [audit](#audit)
- [check](#check)
- [phi-check](#phi-check)
- [diff](#diff)
- [extract](#extract)
- [table](#table)
- [abi](#abi)
- [binary](#binary)
- [run](#run)
- [test](#test)
- [watch](#watch)
- [pipeline](#pipeline)
- [fixedpoint](#fixedpoint)
- [status](#status)
- [init](#init)
- [Template Engine](#template-engine)
- [How it works](#how-it-works)
- [Template specification](#template-specification)
- [Matcher types](#matcher-types)
- [Extractors](#extractors)
- [Autofix](#autofix)
- [Writing custom templates](#writing-custom-templates)
- [Workflows](#workflows)
- [Workflow specification](#workflow-specification)
- [Shipped workflows](#shipped-workflows)
- [Shipped Templates](#shipped-templates)
- [ABI templates](#abi-templates)
- [IR templates](#ir-templates)
- [Binary templates](#binary-templates)
- [Bootstrap templates](#bootstrap-templates)
- [Output Formats](#output-formats)
- [Configuration: culebra.toml](#configuration-culebratoml)
- [Template Directory](#template-directory)
- [Exit Codes](#exit-codes)
- [CI/CD Integration](#cicd-integration)
---
## Installation
### From crates.io (when published)
```bash
cargo install culebra
```
### From GitHub
```bash
cargo install --git https://github.com/Mapanare-Research/Culebra
```
### From source
```bash
git clone https://github.com/Mapanare-Research/Culebra.git
cd Culebra
cargo build --release
# Binary at target/release/culebra
```
### WSL / Linux
```bash
# Install Rust if needed
# Build and install
cd /path/to/Culebra
cargo install --path .
```
---
## Commands Reference
### scan
Scan IR files with YAML pattern templates. This is the Nuclei-style template engine.
```
culebra scan <FILE> [OPTIONS]
```
**Arguments:**
- `<FILE>` -- Path to `.ll` file
**Options:**
| `--tags <TAGS>` | Filter by tags, comma-separated (e.g., `abi,string`) |
| `--severity <SEVERITY>` | Filter by severity, comma-separated (`critical,high,medium,low,info`) |
| `--id <ID>` | Run a specific template by ID |
| `--template <PATH>` | Path to custom template file or directory |
| `--header <PATH>` | Path to C header for cross-reference checks |
| `--format <FORMAT>` | Output format: `text` (default), `json`, `sarif`, `markdown` |
| `--autofix` | Apply auto-fixes from matching templates |
| `--dry-run` | Show fixes without applying (use with `--autofix`) |
**Examples:**
```bash
# Run all templates against an IR file
culebra scan stage2.ll
# Only ABI and string-related checks
culebra scan stage2.ll --tags abi,string
# Only critical severity
culebra scan stage2.ll --severity critical
# Run one specific template
culebra scan stage2.ll --id unaligned-string-constant
# Cross-reference IR struct layouts against C header
culebra scan stage2.ll --header runtime/mapanare_core.c
# Output as JSON for programmatic consumption
culebra scan stage2.ll --format json
# Output as SARIF for GitHub Code Scanning
culebra scan stage2.ll --format sarif > results.sarif
# Preview auto-fixes without applying
culebra scan stage2.ll --autofix --dry-run
# Apply auto-fixes
culebra scan stage2.ll --autofix
# Use a custom template directory
culebra scan stage2.ll --template ./my-templates/
```
**Exit codes:**
- `0` -- No critical or high findings
- `1` -- One or more critical or high findings detected
---
### templates
Browse and inspect available scan templates.
#### templates list
```bash
culebra templates list [--tags <TAGS>]
```
Lists all templates with their ID, severity, name, and tags.
```bash
# List all
culebra templates list
# Filter by tag
culebra templates list --tags abi
culebra templates list --tags bootstrap
```
**Example output:**
```
culebra 29 templates in culebra-templates
ID SEVERITY NAME TAGS
----------------------------------------------------------------------------------------------------
empty-switch-body critical Switch statement with zero cases ir, control-flow
unaligned-string-constant critical String constant missing alignment abi, string
direct-push-no-writeback high List push without temp writeback abi, sret
...
```
#### templates show
```bash
culebra templates show <ID>
```
Shows full details of a template: description, impact, remediation steps, CWE reference, related templates.
```bash
culebra templates show unaligned-string-constant
```
**Example output:**
```
Template: unaligned-string-constant
Name: String constant missing alignment
Severity: critical
Author: juandenis
CWE: CWE-188
Tags: abi, string, bootstrap-killer, silent-failure
Description:
String constants without align 2+ can land at odd addresses.
Runtimes using pointer tagging will mangle these pointers,
causing silent string comparison failures.
Impact:
All string comparisons return false. Tokenizer produces 0 tokens.
No crash, no error, just silent empty output.
Remediation:
Add ', align 2' to all [N x i8] constant declarations
>> auto-fixable (line_replace)
Difficulty: trivial
Related:
- raw-control-byte-in-constant
- tagged-pointer-odd-address
```
---
### workflow
Run a multi-step scan workflow. Workflows chain templates with stop conditions.
```
culebra workflow <WORKFLOW_ID> [OPTIONS]
```
**Arguments:**
- `<WORKFLOW_ID>` -- Workflow ID to run
**Options:**
| `--input <KEY=VALUE>` | Input files as key=value pairs (repeatable) |
| `--format <FORMAT>` | Output format: `text`, `json`, `sarif`, `markdown` |
**Examples:**
```bash
# Run bootstrap health check
culebra workflow bootstrap-health-check \
--input stage1_output=stage1.ll
# Pre-commit validation
culebra workflow pre-commit \
--input ir_file=main.ll
# Full CI scan with SARIF output
culebra workflow ci-full \
--input ir_file=main.ll \
--format sarif > results.sarif
```
---
### strings
Validate `[N x i8] c"..."` string constant byte counts in LLVM IR.
```
culebra strings <FILE> [--verbose] [--json]
```
Catches byte-count mismatches caused by escape-sequence miscounting. The declared `[N x i8]` says N bytes, but the actual `c"..."` content may have a different count when `\xx` hex escapes are properly counted.
**Options:**
| `--verbose` / `-v` | Show duplicate string details |
| `--json` | Output as JSON |
---
### audit
Detect known IR pathologies.
```
culebra audit <FILE> [--only <FILTER>] [--baseline <FILE>]
```
Built-in detectors:
- **EMPTY_SWITCH** -- `switch` with 0 cases (match arms not generated)
- **RET_TYPE_MISMATCH** -- `ret` type doesn't match function signature
- **MISSING_PERCENT** -- Bare identifiers missing `%` prefix
- **DUPLICATE_CASE** -- Duplicate values in switch case list
**Options:**
| `--only <FILTER>` | Filter functions by substring |
| `--baseline <FILE>` | Save baseline for delta tracking |
---
### check
Validate IR with `llvm-as`.
```
culebra check <FILE>
```
Runs `llvm-as` (auto-detects versions 15-18) and reports structured errors. Returns 0 if valid, 1 if invalid.
---
### phi-check
Validate that a transform script preserves IR structure.
```
culebra phi-check <FILE> [--fix-cmd <CMD>]
```
Runs the transform command, then compares before/after: function counts, line counts, structural changes. Catches scripts that silently delete functions or produce empty output.
**Options:**
| `--fix-cmd <CMD>` | Transform command (default: `python3 scripts/fix_stage2_phis.py -`) |
---
### diff
Per-function structural diff between two IR files.
```
culebra diff <FILE_A> <FILE_B> [--verbose]
```
Uses register-normalized structural hashing to compare functions. Reports:
- **Matched** -- Same structure (ignoring register names)
- **Diverged** -- Different structure with metric deltas
- **Only in A / Only in B** -- Functions present in one file but not the other
**Options:**
| `--verbose` / `-v` | Show per-instruction diffs for divergent functions |
---
### extract
Extract one function's IR from a file.
```
culebra extract <FILE> <FUNC_NAME>
```
Searches by exact name or substring match. Outputs the full function definition with metrics (instructions, allocas, calls, etc.).
---
### table
Per-function metrics table.
```
culebra table <FILE> [--top <N>] [--sort-by <METRIC>]
```
Displays a table of per-function metrics. Useful for finding the most complex functions.
**Options:**
| `--top <N>` | Show top N functions only |
| `--sort-by <METRIC>` | Sort column: `instructions` (default), `allocas`, `calls`, `blocks`, `stores`, `loads`, `geps` |
---
### abi
Validate struct layouts and calling conventions.
```
culebra abi <FILE> [--header <C_HEADER>]
```
Detects:
- Structs larger than 16 bytes returned by value (should use sret)
- sret/byref attribute misuse
- Field count/type mismatches between IR `%struct.*` types and C `typedef struct`
**Options:**
| `--header <PATH>` | Path to C header or source file for cross-reference |
---
### binary
Inspect compiled binary and cross-reference against IR.
```
culebra binary <FILE> [--ir <IR_FILE>] [--find <STRING>]
```
Parses ELF or PE binaries using the `goblin` crate. Extracts readable strings from `.rodata`, inspects the symbol table, and optionally cross-references string addresses against IR GEP targets.
**Options:**
| `--ir <PATH>` | Path to `.ll` file for cross-referencing GEP targets |
| `--find <STRING>` | Verify a specific string exists at correct address |
---
### run
Compile and run a single test.
```
culebra run <COMPILER> <SOURCE> [OPTIONS]
```
Compiles a source file through the specified compiler, links with clang, runs the binary, and optionally checks stdout against expected output.
**Options:**
| `--expect <OUTPUT>` | Expected stdout (fail if different) |
| `--timeout <SECS>` | Timeout in seconds (default: 30) |
| `--clang-flags <FLAGS>` | Extra flags passed to clang when linking |
| `--runtime <PATH>` | Path to C runtime to link |
---
### test
Run all tests from `culebra.toml`.
```
culebra test [--config <FILE>] [--filter <NAME>] [--timeout <SECS>]
```
Reads `[[tests]]` entries from the config, compiles each source, runs the binary, and diffs stdout against expected output.
**Options:**
| `--config` / `-c` | Config file (default: `culebra.toml`) |
| `--filter` | Filter tests by name substring |
| `--timeout` | Timeout per test in seconds (default: 30) |
---
### watch
Watch files and re-run a command on change.
```
culebra watch [--patterns <GLOBS>] [--dir <DIR>] <CMD...>
```
Uses filesystem notifications (inotify on Linux, ReadDirectoryChanges on Windows) to detect changes and re-run the specified command.
**Options:**
| `--patterns` / `-p` | Glob patterns to watch, comma-separated (default: `*.ll,*.mn`) |
| `--dir` / `-d` | Directory to watch (default: `.`) |
---
### pipeline
Run a full bootstrap stage pipeline.
```
culebra pipeline [--config <FILE>] [--timeout <SECS>]
```
Reads `[[stages]]` from `culebra.toml` and runs them sequentially. Each stage's command can reference `{input}`, `{output}`, and `{prev_output}`. Optionally validates each stage's output with `llvm-as`.
**Options:**
| `--config` / `-c` | Config file (default: `culebra.toml`) |
| `--timeout` | Per-step timeout in seconds (default: 30) |
---
### fixedpoint
Detect fixed-point convergence in self-hosting compilers.
```
culebra fixedpoint <COMPILER> <SOURCE> [OPTIONS]
```
Compiles the source N times, each time using the previous output as the compiler. Compares outputs between iterations. A self-hosting compiler should reach a fixed point (identical output) within 2-3 iterations.
**Options:**
| `--max-iters <N>` | Maximum iterations before giving up (default: 3) |
| `--timeout <SECS>` | Timeout per compilation (default: 120) |
| `--runtime <PATH>` | Path to C runtime to link |
---
### status
Show bootstrap self-hosting progress.
```
culebra status [--config <FILE>]
```
Reads `culebra.toml` and displays project info, stage names, and test counts.
---
### init
Generate a `culebra.toml` starter config.
```
culebra init
```
Creates a `culebra.toml` with example `[project]`, `[[stages]]`, and `[[tests]]` sections.
---
## Template Engine
### How it works
Culebra's template engine is inspired by [Nuclei](https://github.com/projectdiscovery/nuclei). Bug patterns are defined as YAML templates. The Rust binary loads templates, parses IR, runs matching logic, and reports findings.
**Flow:**
1. Templates are loaded from `culebra-templates/` (or `--template` path)
2. Templates are filtered by `--tags`, `--severity`, `--id`
3. The input `.ll` file is parsed into an IR module (functions, globals, string constants, struct types)
4. Each template's matchers run against the appropriate section of the IR
5. Findings are collected, sorted by severity, and output in the requested format
6. If `--autofix` is set, applicable fixes are applied
### Template specification
Every template is a YAML file with the following structure:
```yaml
# Required: unique identifier
id: my-template-id
# Required: metadata
info:
name: Human-readable name # Required
description: | # Optional, multiline
Detailed description of the bug pattern.
tags: # Optional, for filtering
- abi
- string
references: # Optional, URLs
- https://example.com/related-issue
cwe: CWE-188 # Optional, CWE identifier
created: "2025-03-28" # Optional
updated: "2025-03-28" # Optional
# Optional: what files/sections this template applies to
scope:
file_type: llvm-ir # llvm-ir | elf-binary | c-header | cross-reference
# Required: matching logic
match:
# ... (see Matcher Types below)
# Optional: extract data from matches for reporting
extractors:
- type: regex
name: variable_name
pattern: 'regex with (capture group)'
group: 1
# Optional: how to display findings
report:
format: |
Use {variable_name} from extractors in the message.
evidence:
show_line: true
show_context: 2
# Optional: how to fix the issue
remediation:
suggestion: "Human-readable fix instructions"
autofix: # Optional, enables --autofix
type: line_replace
match: 'regex to match'
replace: 'replacement string'
# Optional: related template IDs
related:
- other-template-id
```
### Matcher types
#### Regex matcher
Matches single-line regex patterns against the selected section.
```yaml
match:
matchers:
- type: regex
name: descriptive_name
pattern:
- 'first regex pattern'
- 'alternative pattern' # any match triggers
# Optional: negate the match
condition: not_contains
# Optional: extract inline
extractor:
name: captured_value
group: 1
condition: or # or | and -- how to combine multiple matchers
```
**Section targeting:**
- `globals` -- Only lines starting with `@` that contain `constant` or `global`
- `functions` -- All lines within function bodies
- `declarations` -- Lines starting with `declare`
- `metadata` -- Lines starting with `!`
- `all` -- Every line in the file
#### Sequence matcher
Multi-line pattern matching within function bodies. Supports captures, forward references, and absence checks.
```yaml
match:
type: sequence
steps:
# Step 1: Find a GEP instruction, capture its output
- id: gep_to_field
pattern: '(%[\w.]+) = getelementptr.* ptr (%[\w.]+), i32 0, i32 (\d+)'
capture:
gep_result: 1 # capture group 1 -> variable "gep_result"
struct_ptr: 2
field_index: 3
# Step 2: Find a call using the captured value, within 10 lines
- id: direct_push
pattern: 'call void @__mn_list_push\(ptr %{gep_result}' # {gep_result} is interpolated
after: gep_to_field # search starts after step 1's match
within_lines: 10 # only search within 10 lines
# Step 3: Absence check -- this pattern must NOT appear
- id: missing_writeback
type: absent # "absent" means this must NOT match
pattern: 'store .+ ptr %{gep_result}'
after: direct_push
within_lines: 15
condition: all # all steps must match (including absence checks)
```
**Key features:**
- **Captures** propagate between steps via `{variable_name}` interpolation
- **`after`** constrains where the search starts (after a previous step's match position)
- **`within_lines`** limits the search window
- **`type: absent`** inverts the match -- the step succeeds if the pattern is NOT found
#### Cross-reference matcher
Compares patterns across two files (e.g., IR struct types vs C header structs). Requires `--header` flag.
```yaml
scope:
file_type: cross-reference
inputs:
ir_file: "*.ll"
c_header: "*.h|*.c"
match:
type: cross_reference
steps:
- id: ir_struct
file: ir_file
pattern: '%struct\.(\w+) = type \{([^}]+)\}'
capture:
struct_name: 1
ir_fields: 2
- id: c_struct
file: c_header
pattern: 'typedef struct \{([^}]+)\} (\w+);'
capture:
c_fields: 1
c_name: 2
- id: compare
type: layout_compare
type_map:
"ptr": ["char *", "void *"]
"i64": ["int64_t", "size_t"]
```
#### Byte scanner
Scans for raw byte values in string constants.
```yaml
match:
matchers:
- type: byte_scan
name: raw_control_chars
byte_range: [1, 31] # scan for bytes 0x01-0x1F
exclude: [10] # exclude newline (0x0A)
condition: or
```
### Extractors
Extractors pull named values from matched text for use in report templates.
```yaml
extractors:
# Regex extractor -- captures a group from the matched text
- type: regex
name: constant_name
pattern: '(@[\w.]+) = '
group: 1
# Computed extractor (stub -- for future engine-level logic)
- type: computed
name: address_parity
method: layout_simulation
```
Extracted values are available in report format strings as `{constant_name}`.
### Autofix
Templates can include auto-fix definitions that modify the source file.
```yaml
remediation:
autofix:
type: line_replace
match: '(constant \[\d+ x i8\] c"[^"]*")\s*$' # regex to match
replace: '\1, align 2' # replacement (supports backrefs)
```
**Usage:**
```bash
# Preview fixes
culebra scan file.ll --autofix --dry-run
# Apply fixes
culebra scan file.ll --autofix
```
The dry-run mode shows a diff-like output of what would change:
```
autofix Dry run -- 2 fixes would be applied:
file.ll:7
- @.str.0 = private constant [6 x i8] c"hello\00"
+ @.str.0 = private constant [6 x i8] c"hello\00", align 2
```
### Writing custom templates
1. Create a YAML file in `culebra-templates/` (or any subdirectory)
2. Define the template following the specification above
3. Run `culebra scan file.ll` -- your template is automatically loaded
**Minimal template:**
```yaml
id: my-check
info:
name: My custom check
severity: medium
tags:
- custom
scope:
file_type: llvm-ir
section: functions
match:
matchers:
- type: regex
name: pattern
pattern:
- 'some pattern to detect'
condition: or
remediation:
suggestion: "How to fix this"
```
**Testing your template:**
```bash
# Run only your template
culebra scan file.ll --id my-check
# Or point to a single file
culebra scan file.ll --template ./my-check.yaml
```
---
## Workflows
Workflows chain multiple template scans with stop conditions. They're defined as YAML files in `culebra-templates/workflows/`.
### Workflow specification
```yaml
id: my-workflow
info:
name: My workflow name
severity: critical
description: What this workflow does.
tags:
- workflow
workflow:
# Step 1: Run IR and string templates
- templates:
tags:
- ir
- string
input: "{stage1_output}" # {var} references resolved from --input flags
stop_on: critical # stop workflow if critical findings appear
# Step 2: Run ABI templates (only if step 1 passed)
- templates:
tags:
- abi
input: "{stage1_output}"
stop_on: critical
# Step 3: Run bootstrap templates
- templates:
tags:
- bootstrap
input: "{stage1_output}"
```
**Key features:**
- **`templates.tags`** -- Select templates by tag for this step
- **`templates.ids`** -- Or select specific template IDs
- **`input`** -- File path with `{variable}` interpolation from `--input` flags
- **`stop_on`** -- Stop the entire workflow if findings at this severity or worse are found
### Shipped workflows
| Workflow | Purpose | Steps |
|---|---|---|
| `bootstrap-health-check` | Full bootstrap validation | IR/string checks -> ABI checks -> bootstrap divergence |
| `pre-commit` | Quick pre-commit gate | IR checks (stop on critical) -> ABI/string checks |
| `ci-full` | Comprehensive CI scan | IR -> ABI/string -> bootstrap (no stop conditions) |
---
## Shipped Templates
### ABI templates
#### `unaligned-string-constant` (Critical)
String constants without `align 2+` can land at odd addresses. Runtimes using pointer tagging (bit 0 masking) will mangle these pointers, causing silent string comparison failures.
**Auto-fixable:** Yes -- appends `, align 2` to constant declarations.
#### `direct-push-no-writeback` (High)
Pushing to a list via GEP directly into a struct field without loading to a temp alloca first. LLVM alias analysis may cache the struct load from before the push, losing the mutation.
**Matcher:** Sequence -- finds GEP -> list_push -> missing store-back pattern.
#### `sret-input-output-alias` (High)
sret output pointer aliasing an input struct pointer. Writes to the return struct corrupt the input mid-computation.
#### `missing-byval-large-struct` (Medium)
Structs larger than 2 registers passed as bare `ptr` without `byval` attribute. Callee may corrupt caller's data.
#### `tagged-pointer-odd-address` (High)
Odd-sized constants without alignment. Pointer tagging systems will misinterpret these.
**Auto-fixable:** Yes.
#### `struct-layout-mismatch` (Critical)
IR struct type and C header struct have different field counts or types. Requires `--header` flag for cross-reference matching.
---
### IR templates
#### `byte-count-mismatch` (High)
`[N x i8]` declaration says N bytes but actual `c"..."` content differs. Causes buffer overread or silent truncation.
#### `empty-switch-body` (Critical)
Switch with 0 cases -- all values fall through to default. Match arms were not generated.
#### `ret-type-mismatch` (Critical)
`ret` instruction type doesn't match function signature. LLVM will reject during verification.
#### `raw-control-byte-in-constant` (Medium)
Raw control bytes (0x01-0x1F) in `c"..."` constants break line-based tooling.
**Matcher:** Byte scanner for control characters.
#### `phi-predecessor-mismatch` (High)
PHI nodes referencing non-existent predecessor blocks. Often caused by IR transforms that modify control flow without updating PHIs.
#### `unreachable-after-branch` (Medium)
Instructions after a terminator (br, ret, switch, unreachable). Dead code that LLVM will reject.
**Matcher:** Sequence -- finds terminator followed by instruction within 3 lines.
---
### Binary templates
#### `odd-address-rodata` (High)
String at odd virtual address in `.rodata` section. Binary-level confirmation of alignment bugs.
#### `missing-symbol` (Critical)
Expected runtime symbol (e.g., `__mn_*`) missing from binary symbol table.
---
### Bootstrap templates
#### `stage-output-divergence` (High)
Flags function/global definitions for stage comparison. Use with `culebra diff` for per-function analysis.
#### `function-count-drop` (Critical)
Flags function definitions to enable count comparison between stages. A drop in function count between stages is a critical bootstrap bug.
#### `fixed-point-delta` (High)
Flags definitions for fixed-point convergence analysis. Use with `culebra fixedpoint` for automatic detection.
---
## Output Formats
### Text (default)
Colored terminal output with severity badges, template IDs, locations, and fix suggestions.
```bash
culebra scan file.ll
```
### JSON
Structured JSON with all finding details, extractions, and metadata.
```bash
culebra scan file.ll --format json
```
```json
{
"file": "file.ll",
"findings_count": 2,
"findings": [
{
"template_id": "unaligned-string-constant",
"template_name": "String constant missing alignment",
"severity": "critical",
"file": "file.ll",
"line": 7,
"function": null,
"matched_text": "@.str.0 = private constant [6 x i8] c\"hello\\00\"",
"description": "...",
"impact": "...",
"suggestion": "Add ', align 2'",
"cwe": "CWE-188",
"tags": ["abi", "string"],
"extractions": {
"constant_name": "@.str.0",
"byte_size": "6"
}
}
]
}
```
### SARIF
[SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) for GitHub Code Scanning integration.
```bash
culebra scan file.ll --format sarif > results.sarif
```
Upload to GitHub:
```bash
# In a GitHub Action:
- name: Run Culebra scan
run: culebra scan main.ll --format sarif > results.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
```
### Markdown
Markdown report with severity summary table and per-finding details. Useful for CI reports, PR comments.
```bash
culebra scan file.ll --format markdown > report.md
```
---
## Configuration: culebra.toml
The `culebra.toml` file configures project-level settings for `test`, `pipeline`, `status`, and other commands.
```toml
[project]
name = "my-compiler"
source_lang = "my-lang"
target = "llvm"
compiler = "./my-compiler"
runtime = "runtime/my_runtime.c"
[[stages]]
name = "bootstrap"
cmd = "python bootstrap/compile.py {input}"
input = "src/compiler.ml"
output = "/tmp/stage1.ll"
validate = true
[[stages]]
name = "stage1"
cmd = "{prev_output} {input}"
input = "src/compiler.ml"
output = "/tmp/stage2.ll"
validate = true
[[tests]]
name = "hello"
source = 'fn main() { print("hello") }'
expect = "hello"
[[tests]]
name = "math"
source = "fn main() { print(2 + 3) }"
expect = "5"
```
**Substitution variables in stage commands:**
| `{input}` | The stage's `input` field |
| `{output}` | The stage's `output` field |
| `{prev_output}` | The previous stage's `output` field |
Generate a starter config with `culebra init`.
---
## Template Directory
Templates are loaded from the first directory found:
1. `./culebra-templates/` (project-local)
2. `<binary_dir>/culebra-templates/` (next to the culebra binary)
3. `~/.culebra/templates/` (user-global)
Override with `--template <PATH>`.
**Recommended structure:**
```
culebra-templates/
abi/
unaligned-string-constant.yaml
direct-push-no-writeback.yaml
sret-input-output-alias.yaml
missing-byval-large-struct.yaml
tagged-pointer-odd-address.yaml
struct-layout-mismatch.yaml
ir/
byte-count-mismatch.yaml
empty-switch-body.yaml
ret-type-mismatch.yaml
raw-control-byte.yaml
phi-predecessor-mismatch.yaml
unreachable-after-branch.yaml
binary/
odd-address-rodata.yaml
missing-symbol.yaml
bootstrap/
stage-output-divergence.yaml
function-count-drop.yaml
fixed-point-delta.yaml
workflows/
bootstrap-health-check.yaml
pre-commit.yaml
ci-full.yaml
```
---
## Exit Codes
| `0` | Success / no critical findings |
| `1` | Error or critical/high findings detected |
For `scan`: exit code 1 if any finding has severity `critical` or `high`. This makes it suitable for CI gates:
```bash
---
## CI/CD Integration
### GitHub Actions
```yaml
name: Culebra Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Culebra
run: cargo install --git https://github.com/Mapanare-Research/Culebra
- name: Run scan
run: culebra scan output.ll --format sarif > culebra.sarif
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: culebra.sarif
```
### Pre-commit hook
```bash
#!/bin/bash
# .git/hooks/pre-commit
culebra scan output.ll --severity critical,high
```
### Generic CI
```bash
# Run scan, fail on critical/high
culebra scan main.ll --severity critical,high
# Full report as markdown artifact
culebra scan main.ll --format markdown > culebra-report.md
# JSON for programmatic processing