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 codeMeaning
0Pass: nothing at or above --fail-on
1Findings at or above --fail-on
2Usage 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.

RuleSeverityCatches
unicode-tag-smugglingcriticalInvisible Unicode tag characters; the hidden text is decoded in the report
hidden-bidi-controlcritical in codeBidirectional overrides that make code read differently than it runs
hidden-zero-widthmediumZero-width characters
instruction-overridehighAttempts to cancel the model's earlier instructions
conceal-from-userhighInstructions to hide something from the user
exfiltration-instructionhighRequests to send credentials, keys or tokens somewhere
auto-approve-instructionhighRequests to skip confirmation or bypass approvals
hidden-comment-instructionhighInstruction-like HTML comments (hidden when rendered)
role-hijackmediumFake system prompts and role changes
credential-path-referencemediumInstructions that mention SSH keys, cloud credentials, etc.
pipe-to-shellmediumcurl/wget piped into a shell, inside agent instructions
encoded-blobmediumLong 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
![Coticula](coticula.svg)

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.