Docs
Coticula v0.1.0 · Python 3.9+ · no dependencies.
Install
pipx install coticula
No pipx? pip install --user coticula works too. Or use the checksum-verified installer:
curl -fsSL https://coticula.kineticdevops.com/install.sh | sh
The installer downloads the wheel, checks its SHA-256, then installs with pipx (or pip --user if pipx is missing). It's short, so read it first:
curl -fsSL https://coticula.kineticdevops.com/install.sh | less
Manual install
curl -fsSLO https://coticula.kineticdevops.com/dl/coticula-0.1.0-py3-none-any.whl shasum -a 256 coticula-0.1.0-py3-none-any.whl # expect ce2b72b9be8b284a0f8b741ad4a69b33ed4cb7e352a7045b0428bf3fd55f875b pipx install ./coticula-0.1.0-py3-none-any.whl
Usage
coticula scan [PATH] # text report, default: current directory coticula scan . --format json -o report.json coticula scan . --format markdown # for PR comments and job summaries coticula scan . --fail-on medium # stricter gate (default: high) coticula scan . --only ai --only secrets coticula scan . --exclude "examples/**" coticula scan . --offline # skip the OSV.dev lookup coticula scan . --show-info # include informational findings coticula init # write coticula.json from detected capabilities coticula badge . -o coticula.svg # README badge
| Exit code | Meaning |
|---|---|
0 | Pass: nothing at or above --fail-on |
1 | Findings at or above --fail-on |
2 | Usage or runtime error |
Checks
ai — text that steers models
Looks at agent instructions (SKILL.md, CLAUDE.md, AGENTS.md, files under skills/, prompts/, .claude/, *.prompt) and MCP server source, where tool names and descriptions are read by the model.
| Rule | Severity | Catches |
|---|---|---|
| unicode-tag-smuggling | critical | Invisible Unicode tag characters; the hidden text is decoded in the report |
| hidden-bidi-control | critical in code | Bidirectional overrides that make code read differently than it runs |
| hidden-zero-width | medium | Zero-width characters |
| instruction-override | high | Attempts to cancel the model's earlier instructions |
| conceal-from-user | high | Instructions to hide something from the user |
| exfiltration-instruction | high | Requests to send credentials, keys or tokens somewhere |
| auto-approve-instruction | high | Requests to skip confirmation or bypass approvals |
| hidden-comment-instruction | high | Instruction-like HTML comments (hidden when rendered) |
| role-hijack | medium | Fake system prompts and role changes |
| credential-path-reference | medium | Instructions that mention SSH keys, cloud credentials, etc. |
| pipe-to-shell | medium | curl/wget piped into a shell, inside agent instructions |
| encoded-blob | medium | Long base64 blobs that can't be reviewed by reading |
In ordinary documentation the same phrases are reported as low, since a README describing an attack isn't an attack.
secrets
Anthropic, OpenAI, AWS, GitHub (classic and fine-grained), Slack, Stripe live and Google API keys; PEM private keys; committed .env files; high-entropy values assigned to names like api_key or password. Obvious placeholders are skipped. Values are always redacted.
deps
Reads requirements*.txt, pyproject.toml (Python 3.11+), package-lock.json and package.json. Exact versions are checked against OSV.dev; ranges and wildcards are flagged as unpinned.
manifest
Detects network access, subprocesses, environment-variable reads, file writes and dynamic code (eval, exec, pickle.loads, new Function) in Python, JavaScript/TypeScript and shell. Test files are excluded. See below.
quality
Starts at 100 and deducts for: no README (−15), no tests (−25), no license (−5), tests that can't fail (−5 each), placeholders and swallowed errors (−2 each), files over 1,500 lines, and heavy TODO density.
Permission manifest
Put coticula.json at the project root. coticula init writes one from what it detects; then narrow it by hand.
{
"name": "my-mcp-server",
"permissions": {
"network": ["api.github.com"],
"filesystem": "read",
"env": ["GITHUB_TOKEN"],
"subprocess": false
},
"ignore": ["tests/fixtures/**"]
}
network and env take true, false or a list. In v0.1.0 lists are documentation for reviewers; host-level enforcement arrives with sandboxed runs. filesystem is none, read or write. Code that uses a capability the manifest doesn't declare is a high finding.
CI
GitHub Actions
- uses: actions/setup-python@v5
with: { python-version: "3.12" }
- run: |
pip install --quiet coticula
coticula scan . --format markdown
When GITHUB_STEP_SUMMARY is set, the markdown report is added to the job summary automatically.
Local pre-push hook (no CI minutes)
printf '#!/bin/sh\ncoticula scan . --offline\n' > .git/hooks/pre-push chmod +x .git/hooks/pre-push
Badge
coticula badge . -o coticula.svg # README.md 
The badge is generated locally and shows the tier and quality score. It's a claim you can re-verify, not a hosted certificate — anyone can run the same scan.
Ignoring findings
Add coticula:ignore in a comment on the line to silence it. Skip whole paths with "ignore" globs in coticula.json or --exclude. Ignores are visible in your code, so reviewers can see them.
Privacy
Scanning happens on your machine. The only network call is to OSV.dev, sending package names and versions (never code). --offline turns that off.
Limits
Coticula v0.1.0 is static and pattern-based. It will miss things a determined attacker hides well, and it will sometimes flag safe code. Scanned means passed these checks, not guaranteed safe. Treat it as a strong first filter, not a replacement for review.