Configuration

Precedence

Sigil resolves configuration from multiple sources. When the same setting appears in more than one place, the highest-priority source wins:

1. CLI flags — always win
2. Environment variables
3. Config file (~/.sigil/config.json) — stored by sigil config; no scan setting reads it in 1.3.6
4. Built-in defaults

Environment variables

Environment variables override built-in defaults. Useful for CI/CD pipelines and per-machine customization.

# Store quarantined code on a separate volume
export SIGIL_QUARANTINE_DIR=/mnt/secure/sigil-quarantine

The cloud API base URL is not an environment variable. The default is https://api.sigilsec.ai; override it per command with --endpoint:

# Point login at your own API instance
sigil login --endpoint https://sigil.internal.mycompany.com

Directory structure

Sigil creates files under ~/.sigil/ on demand as you use each feature:

~/.sigil/
├── quarantine/     # Quarantined items + index.json (sigil clone/pip/npm)
├── ledger/         # Trust ledger (sigil ledger)
├── providers/      # Credential providers for sigil run
├── config.json     # Key/value store written by sigil config
├── token           # Auth token (after sigil login)
└── signatures.json # Cached cloud signatures (after sigil fetch)

Config file

sigil config stores free-form string key/value pairs as JSON at ~/.sigil/config.json. In 1.3.6 the scanner does not read any key from this file — scan behavior is set with CLI flags such as --severity, --phases and --fail-on.

# Print the whole file
sigil config --list

# Read one key
sigil config <key>

# Set a key
sigil config <key> <value>

Running sigil config with no arguments exits 1 and asks for a key or --list. One separate plain-text file is read: a line disclaimer=false in ~/.sigil/config suppresses the review-your-code notice printed after each scan.

.sigilignore

Place a .sigilignore file at the root of the directory being scanned. It uses glob syntax similar to .gitignore.

# Directories
node_modules/
.git/
__pycache__/
vendor/
dist/
build/

# File patterns
*.min.js
*.bundle.js
*.map
*.lock

# Specific files
package-lock.json
yarn.lock
poetry.lock

Default exclusions

Even without a .sigilignore file, Sigil skips these directory names at any depth:

• node_modules/
• .git/
• target/
• .next/
• __pycache__/
• .venv/ and venv/
• .tox/
• .mypy_cache/ and .pytest_cache/

Tests, examples, docs and dotfiles are scanned — markdown and instruction files like .cursorrules are prompt-injection targets. .gitignore is honored only inside a real git checkout, so a .gitignore in an extracted package tarball cannot hide files from the scan.

Pattern rules

Scan policies

Pro and Team plans support scan policies stored in the Sigil cloud and shared by everyone on the team. A policy has a name, a type (one of the four below), a config object and an enabled flag. Configure policies via the dashboard or API.

Auto-approve threshold

Type auto_approve_threshold. A scan whose risk score is at or below max_risk_score is marked auto-approved; a scan above it is recorded as a policy violation. When the key is omitted the threshold is 10.

{ "max_risk_score": 0 }

To require manual review for everything, do not create a threshold policy.

Required phases

Type required_phases. A submitted scan that has no finding from each listed phase is a violation. Phase identifiers: install_hooks, code_patterns, network_exfil, credentials, obfuscation, provenance, prompt_injection, skill_security.

{ "phases": ["install_hooks", "prompt_injection"] }

Package allowlist

Type allowlist. When the list has entries, a scan target that is not on it is a violation. An empty list has no effect. Allowlisted targets are still scanned.

{
  "packages": [
    "@myorg/shared-utils",
    "@myorg/config"
  ]
}

Package blocklist

Type blocklist. A scan target on the list is a violation, regardless of scan results.

{
  "packages": [
    "malicious-package-name",
    "deprecated-unsafe-lib"
  ]
}

Policy API

Policies live in the Sigil cloud under /v1/policies. Evaluation is server-side: POST /v1/policies/evaluate takes a scan result and returns allowed, violations and auto_approved. Use the token from ~/.sigil/token:

# List policies
curl -H "Authorization: Bearer $(cat ~/.sigil/token)" \
  https://api.sigilsec.ai/v1/policies

# Create a policy
curl -X POST -H "Authorization: Bearer $(cat ~/.sigil/token)" \
  -H "Content-Type: application/json" \
  -d '{"name": "clean only", "type": "auto_approve_threshold", "config": {"max_risk_score": 0}, "enabled": true}' \
  https://api.sigilsec.ai/v1/policies

# Update or delete by id
curl -X PUT -H "Authorization: Bearer $(cat ~/.sigil/token)" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' \
  https://api.sigilsec.ai/v1/policies/<policy_id>
curl -X DELETE -H "Authorization: Bearer $(cat ~/.sigil/token)" \
  https://api.sigilsec.ai/v1/policies/<policy_id>

Shell aliases

Sigil can install three convenience aliases into your shell configuration.

Installation

Reads $SHELL (bash or zsh) and appends the alias block to ~/.bashrc or ~/.zshrc. Re-running it never duplicates the block.

sigil setup shell

The installer writes the same block when run with install.sh --with-aliases.

Alias definitions

Other shells

If $SHELL is not bash or zsh, Sigil prints the aliases instead of writing them. Add them to your shell config by hand:

alias gclone='sigil clone' safepip='sigil pip' safenpm='sigil npm'

Removing aliases

Delete the block between the # >>> sigil aliases >>> and # <<< sigil aliases <<< markers in your shell configuration file.

Git hooks

Sigil can install a pre-commit hook that scans the whole repository with the standard scan phases before every commit.

Installation

Run inside the repository (there is no path argument):

cd /path/to/repo && sigil setup git

If a pre-commit hook that Sigil did not write already exists, it is left untouched and Sigil prints the line to add to it manually.

Behavior

The hook runs sigil scan . --fail-on high. A HIGH or CRITICAL finding exits 1 and blocks the commit; findings are the same ones documented under scan phases in the CLI reference. If sigil is not on PATH the hook prints a warning and lets the commit through. To bypass the hook for a specific commit:

git commit --no-verify -m "known safe: template engine uses eval"

Authentication

Sigil uses JWT tokens for cloud features (Pro and Team plans). The open-source CLI works entirely offline without authentication.

Token storage

sigil login stores the token at ~/.sigil/token. Sigil reads it whenever a cloud command runs and continues with local results if the token is missing or the API is unreachable.

What data is sent

Nothing is sent to the Sigil cloud API unless you pass an opt-in flag to sigil scan. What each flag sends: