Coticula
Test before you trust. Coticula (koh-TIK-yoo-lah, Latin for touchstone) scans MCP servers, agent skills, plugins and reusable code for the problems a careful reviewer would catch — before you bolt them onto your project.
curl -fsSL https://coticula.kineticdevops.com/install.sh | sh
coticula scan .
What it checks
| Check | What it finds |
|---|---|
secrets |
Leaked API keys (Anthropic, OpenAI, AWS, GitHub, Slack, Stripe, Google), private keys, committed .env files, high-entropy hard-coded secrets. Snippets are always redacted. |
deps |
Known vulnerabilities in pinned Python and npm dependencies via OSV.dev, plus unpinned versions. |
ai |
Text that tries to steer the model reading it: instruction overrides, "don't tell the user", exfiltration requests, auto-approve instructions, hidden HTML comments, encoded blobs — in SKILL.md, prompts, CLAUDE.md/AGENTS.md and MCP tool descriptions. Invisible Unicode (tag-character smuggling, bidi controls, zero-width) anywhere. |
manifest |
Compares what your code does (network, subprocess, environment variables, file writes, eval) against what coticula.json declares. |
quality |
Missing README/tests/license, tests that can't fail, placeholders, swallowed errors, oversized files. Produces a 0–100 quality score. |
A project with no high or critical findings earns the Scanned tier and a badge.
Usage
coticula scan [PATH] # text report (default: current dir)
coticula scan . --format json -o report.json
coticula scan . --format markdown # for PR comments
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 lookup
coticula init # generate coticula.json from detected capabilities
coticula badge . -o coticula.svg # README badge
Exit codes: 0 pass · 1 findings at or above --fail-on · 2 error.
Silence a single line with a trailing coticula:ignore comment. Skip paths with "ignore" globs in coticula.json.
Permission manifest
{
"name": "my-mcp-server",
"permissions": {
"network": ["api.github.com"],
"filesystem": "read",
"env": ["GITHUB_TOKEN"],
"subprocess": false
},
"ignore": ["tests/fixtures/**"]
}
network and env accept true, false or a list (lists are documentation in v0.1; host-level enforcement arrives with sandboxed runs). filesystem is none, read or write.
CI
Run it anywhere Python 3.9+ runs. On GitHub:
- uses: actions/setup-python@v5
with: { python-version: "3.12" }
- run: |
curl -fsSL https://coticula.kineticdevops.com/install.sh | sh
coticula scan . --format markdown
The markdown report is also appended to the job summary automatically when GITHUB_STEP_SUMMARY is set.
Limits (v0.1)
Detection is static and pattern-based. It will miss things a determined attacker hides well, and it will occasionally flag safe code. "Scanned" means passed these checks, not guaranteed safe. Sandboxed runtime verification and human review tiers are on the roadmap.
Development
pip install -e . pytest
pytest
coticula scan . # Coticula scans itself in CI
Docs: https://coticula.kineticdevops.com/docs
License: to be decided before public release.
Metadata
Release files for coticula 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| coticula-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for coticula-0.1.0-py3-none-any.whl |
Release files / coticula-0.1.0-py3-none-any.whl
| Download URL | coticula-0.1.0-py3-none-any.whl |
|---|---|
| Size | 24.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ce2b72b9be8b284a0f8b741ad4a69b33ed4cb7e352a7045b0428bf3fd55f875b
|
|
BLAKE2b-256 checksum How to use checksums |
3c2ffe7e6c942a4f1ebc422c7fc8338116a75bf33e7f95575dd83826901fda80
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
Security for coticula 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.