Skip to content
Back to search

coticula

Test before you trust: security and quality scanner for MCP servers, agent skills, plugins and reusable code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stalwart42--coticula/badge.svg)](/listings/stalwart42--coticula)

HTML

<a href="/listings/stalwart42--coticula"><img src="/api/listings/stalwart42--coticula/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 87 lines · 1 finding marked
  1. # Coticula
  2. **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.
  3. ```
  4. pipx install coticula
  5. coticula scan .
  6. ```
  7. No pipx? `pip install --user coticula` works too. Prefer a checksum-verified installer? `curl -fsSL https://coticula.kineticdevops.com/install.sh | sh` (read it first).
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 10 on GitHub
  8. ## What it checks
  9. | Check | What it finds |
  10. |---|---|
  11. | `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. |
  12. | `deps` | Known vulnerabilities in pinned Python and npm dependencies via [OSV.dev](https://osv.dev), plus unpinned versions. |
  13. | `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. |
  14. | `manifest` | Compares what your code does (network, subprocess, environment variables, file writes, eval) against what `coticula.json` declares. |
  15. | `quality` | Missing README/tests/license, tests that can't fail, placeholders, swallowed errors, oversized files. Produces a 0–100 quality score. |
  16. A project with no **high** or **critical** findings earns the **Scanned** tier and a badge.
  17. ## Usage
  18. ```
  19. coticula scan [PATH] # text report (default: current dir)
  20. coticula scan . --format json -o report.json
  21. coticula scan . --format markdown # for PR comments
  22. coticula scan . --fail-on medium # stricter gate (default: high)
  23. coticula scan . --only ai --only secrets
  24. coticula scan . --exclude "examples/**"
  25. coticula scan . --offline # skip the OSV lookup
  26. coticula init # generate coticula.json from detected capabilities
  27. coticula badge . -o coticula.svg # README badge
  28. ```
  29. Exit codes: `0` pass · `1` findings at or above `--fail-on` · `2` error.
  30. Silence a single line with a trailing `coticula:ignore` comment. Skip paths with `"ignore"` globs in `coticula.json`.
  31. ## Permission manifest
  32. ```json
  33. {
  34. "name": "my-mcp-server",
  35. "permissions": {
  36. "network": ["api.github.com"],
  37. "filesystem": "read",
  38. "env": ["GITHUB_TOKEN"],
  39. "subprocess": false
  40. },
  41. "ignore": ["tests/fixtures/**"]
  42. }
  43. ```
  44. `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`.
  45. ## CI
  46. Run it anywhere Python 3.9+ runs. On GitHub:
  47. ```yaml
  48. - uses: actions/setup-python@v5
  49. with: { python-version: "3.12" }
  50. - run: |
  51. pip install --quiet coticula
  52. coticula scan . --format markdown
  53. ```
  54. The markdown report is also appended to the job summary automatically when `GITHUB_STEP_SUMMARY` is set.
  55. ## Limits (v0.1)
  56. 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.
  57. ## Development
  58. ```
  59. pip install -e . pytest
  60. pytest
  61. coticula scan . # Coticula scans itself in CI
  62. ```
  63. Docs: https://coticula.kineticdevops.com/docs
  64. License: to be decided before public release.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.