Skip to content
Back to search

mustachecase

MarketplaceWorks with Claude CodeGitHub

zanadir's Claude Code plugins: review and harden a repository's CI with zanadir.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/MustacheCase/zanadir with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/MustacheCase/zanadir'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mustachecase--zanadir/badge.svg)](/listings/mustachecase--zanadir)

HTML

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

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Try it on any public repository without installing anything:

docker run --rm mustachecase/zanadir scan --repo github.com/owner/name

To install it, download the archive for Linux, macOS or Windows (amd64 or arm64) from the [latest release](https://github.com/MustacheCase/zanadir/releases/latest). `checksums.txt` lists each archive's SHA-256, and every archive has a build provenance attestation:

gh attestation verify zanadir_<version>_linux_amd64.tar.gz --repo MustacheCase/zanadir

Or with Homebrew (the tap is this repository) or Go:

brew tap --custom-remote MustacheCase/zanadir https://github.com/MustacheCase/zanadir.git
brew install mustachecase/zanadir/zanadir
go install github.com/MustacheCase/zanadir@latest

In GitHub Actions, use [zanadir-action](https://github.com/MustacheCase/zanadir-action). This workflow reports on every pull request without failing it:

# .github/workflows/zanadir.yml
name: zanadir
on: [pull_request]
permissions:
  contents: read
jobs:
  zanadir:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: mustachecase/zanadir-action@v1.26
        with:
          dir: .

When you are ready to gate, add `enforce: true` (fail on any uncovered category), `fail-on` (only the categories you name) or `fail-on-weakened`. To post the report as a pull request comment, see [Posting the report to a pull request](#posting-the-report-to-a-pull-request).

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.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "mustachecase",
  3. "description": "zanadir's Claude Code plugins: review and harden a repository's CI with zanadir.",
  4. "owner": {
  5. "name": "MustacheCase"
  6. },
  7. "plugins": [
  8. {
  9. "name": "zanadir",
  10. "source": "./plugins/zanadir",
  11. "description": "Find what a repository's CI is missing, and which controls cannot fail a build, then close the gaps with zanadir."
  12. }
  13. ]
  14. }
README.md · README · 1,290 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://github.com/user-attachments/assets/88b976b4-cc46-4706-a3e4-3cfa0e6877d5" alt="zanadir">
  3. </p>
  4. <p align="center">
  5. <a href="#coverage-score"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/MustacheCase/zanadir/badges/zanadir-badge.json" alt="zanadir coverage"></a>
  6. <a href="https://pkg.go.dev/github.com/MustacheCase/zanadir"><img src="https://pkg.go.dev/badge/github.com/MustacheCase/zanadir.svg" alt="Go Reference"></a>
  7. <a href="https://codecov.io/gh/MustacheCase/zanadir"><img src="https://codecov.io/gh/MustacheCase/zanadir/branch/main/graph/badge.svg" alt="Test coverage"></a>
  8. <a href="https://github.com/MustacheCase/zanadir/releases/latest"><img src="https://img.shields.io/github/v/release/MustacheCase/zanadir" alt="Latest release"></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/github/license/MustacheCase/zanadir" alt="License: MIT"></a>
  10. </p>
  11. zanadir is an open-source CI/CD security tool. It reads a repository's
  12. pipeline, from GitHub Actions to GitLab CI, and reports which security and
  13. quality checks are missing, or wired so they cannot fail a build.
  14. ## What it answers
  15. - **What is my pipeline missing?** Thirteen categories, from dependency
  16. scanning and secrets detection to SBOMs, workflow hardening and agent
  17. skill scanning, each
  18. checked against the tools that cover it, with suggestions that fit the
  19. repository's languages.
  20. - **Does my CI actually block on security findings?** A scanner with
  21. `continue-on-error`, `|| true`, a push-only trigger or `allow_failure`, or
  22. one that only reports unless told to fail, like `trivy` without
  23. `--exit-code 1`, is present but cannot stop a merge. zanadir grades each
  24. control *enforcing*, *partial*, *advisory* or *unknown* rather than just
  25. covered; see [Effectiveness](#effectiveness).
  26. - **Is that check required to merge?** With `--required-checks`, a control
  27. only counts as enforcing when branch protection or a ruleset requires it.
  28. - **What do I add?** `zanadir fix` prints ready-to-paste CI configuration for
  29. the gaps, or writes a workflow with `--write`.
  30. It reads GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, Azure
  31. Pipelines and Jenkins, from a checkout (`--dir`) or straight from GitHub
  32. (`--repo`), and reports as a table, JSON, SARIF or Markdown. To see it on a
  33. public repository first, [scan it in your browser](https://mustachecase.github.io/scan/).
  34. For how it maps to the OWASP Top 10 CI/CD Security Risks, and how it differs
  35. from OpenSSF Scorecard, see [the mapping](https://mustachecase.github.io/owasp-cicd-top-10/)
  36. and [the comparison](https://mustachecase.github.io/compare/openssf-scorecard/).
  37. How common are these gaps? The [State of CI security 2026](https://mustachecase.github.io/state-of-ci/)
  38. scanned 1,000 of the most-starred GitHub repositories: 511 declare no
  39. dependency, secret or code scanning at all, and 1 in 6 of those that run a
  40. scanner in CI have one that cannot fail the build.
  41. ```sh
  42. zanadir scan --dir .
  43. zanadir scan --repo github.com/owner/name --output json
  44. zanadir fix --dir .
  45. ```
  46. ## Installation
  47. Try it on any public repository without installing anything, in your
  48. browser at [mustachecase.github.io/scan](https://mustachecase.github.io/scan/)
  49. (zanadir runs there as WebAssembly, and the repository's files never leave
  50. your browser), or with Docker:
  51. ```sh
  52. docker run --rm mustachecase/zanadir scan --repo github.com/owner/name
  53. ```
  54. To install it, download the archive for Linux, macOS or Windows (amd64 or
  55. arm64) from the [latest release](https://github.com/MustacheCase/zanadir/releases/latest).
  56. `checksums.txt` lists each archive's SHA-256, and every archive has a build
  57. provenance attestation:
  58. ```sh
  59. gh attestation verify zanadir_<version>_linux_amd64.tar.gz --repo MustacheCase/zanadir
  60. ```
  61. Or with Homebrew (the tap is this repository) or Go:
  62. ```sh
  63. brew tap --custom-remote MustacheCase/zanadir https://github.com/MustacheCase/zanadir.git
  64. brew install mustachecase/zanadir/zanadir
  65. go install github.com/MustacheCase/zanadir@latest
  66. ```
  67. In GitHub Actions, use [zanadir-action](https://github.com/MustacheCase/zanadir-action).
  68. This workflow reports on every pull request without failing it:
  69. ```yaml
  70. # .github/workflows/zanadir.yml
  71. name: zanadir
  72. on: [pull_request]
  73. permissions:
  74. contents: read
  75. jobs:
  76. zanadir:
  77. runs-on: ubuntu-latest
  78. steps:
  79. - uses: actions/checkout@v4
  80. with:
  81. fetch-depth: 0
  82. - uses: mustachecase/zanadir-action@v1.41
  83. with:
  84. dir: .
  85. ```
  86. When you are ready to gate, add `enforce: true` (fail on any uncovered
  87. category), `fail-on` (only the categories you name) or `fail-on-weakened`. To
  88. post the report as a pull request comment, see
  89. [Posting the report to a pull request](#posting-the-report-to-a-pull-request).
  90. ## zanadir and OpenSSF Scorecard
  91. [OpenSSF Scorecard](https://github.com/ossf/scorecard) and zanadir answer
  92. different questions, and work well together.
  93. | | OpenSSF Scorecard | zanadir |
  94. | --- | --- | --- |
  95. | Question | How healthy are this project's security practices? | Which CI controls are missing, and can the ones present fail a build? |
  96. | Scope | 20 checks across the project: branch protection, code review, maintenance, pinned dependencies, token permissions, signed releases, known vulnerabilities, fuzzing and more | 13 categories of CI controls, each matched against the many tools that provide it |
  97. | Reads | The forge's API: GitHub and GitLab repositories, recent pull requests and check runs | The CI configuration: six CI platforms, the Makefiles, Taskfiles, tox, composite actions and templates its jobs call |
  98. | SAST, for example | Looks for CodeQL or SonarCloud; its docs note other tools may score low | Recognises Semgrep, CodeQL, gosec, Bandit, Brakeman, SonarQube and others, and grades whether each can fail the build |
  99. | Result | A 0-10 score per check and overall | Covered or not per category, graded enforcing, partial, advisory or unknown, with fixes |
  100. Use Scorecard for a project-wide security posture, and zanadir to find out
  101. whether the CI you have would actually stop a bad change, and what to add.
  102. ## Using zanadir with AI coding agents
  103. To have a coding agent check CI with zanadir before changing it, add this to
  104. the repository's `AGENTS.md`, `CLAUDE.md` or equivalent:
  105. ```markdown
  106. ## CI changes
  107. Before adding or changing CI configuration, run `zanadir scan --dir . --output json`
  108. (install: https://github.com/MustacheCase/zanadir#installation). It lists the
  109. missing CI controls and grades each present one: `enforcing` can fail a merge,
  110. `partial`, `advisory` and `unknown` cannot or may not. Fix advisory controls before
  111. adding tools, and use `zanadir fix --dir .` for configuration that fits this
  112. repository. Re-run the scan to confirm the change.
  113. ```
  114. ### As an MCP server
  115. `zanadir mcp` serves three read-only tools over the Model Context Protocol, so
  116. any agent that speaks MCP can grade CI, and check agent skills, before and
  117. after changing them:
  118. - `scan` returns the JSON report: the score, uncovered categories with
  119. suggested tools, and weakened controls with their verdicts;
  120. - `fix` returns ready-to-paste configuration for the gaps, and writes nothing;
  121. - `skills` returns [`zanadir skills`](#zanadir-skills)' JSON: the skills found
  122. and their problems.
  123. Each takes `dir` (a local checkout, by default the current directory) or
  124. `repo` (`github.com/owner/name[@ref]`, read without cloning); `scan` and
  125. `fix` also take `excludedCategories`.
  126. An agent can be steered by what it reads, so the server keeps its tools to
  127. what you started it with. A `dir` must be inside `--dir` (by default the
  128. directory the server starts in); a relative one is read from there. `repo`
  129. fetches are anonymous, so they reach public repositories only, unless you
  130. start the server with `--repo-token` to let them use `GITHUB_TOKEN` or
  131. `GH_TOKEN`.
  132. ```sh
  133. claude mcp add zanadir -- zanadir mcp
  134. ```
  135. It is listed in the [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=zanadir)
  136. as `io.github.MustacheCase/zanadir`, where it runs from the Docker image with
  137. your repository mounted read-only. For other clients, such as Cursor, VS Code
  138. or Windsurf:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "zanadir": { "command": "zanadir", "args": ["mcp"] }
  143. }
  144. }
  145. ```
  146. ### As a Claude Code plugin
  147. In Claude Code, the zanadir plugin brings both: the MCP server, and a skill
  148. that scans, reads your CI configuration, recommends fixes in priority order,
  149. and edits files only after you choose. The server runs the installed
  150. `zanadir` if it is 0.18.0 or later, and otherwise the Docker image.
  151. ```
  152. /plugin marketplace add MustacheCase/zanadir
  153. /plugin install zanadir@mustachecase
  154. ```
  155. Then ask Claude Code to review or harden your CI, or run `/zanadir:improve-ci`.
  156. [`llms.txt`](llms.txt) summarises zanadir for agents that read the repository, and is
  157. served at [mustachecase.github.io/llms.txt](https://mustachecase.github.io/llms.txt)
  158. for those that look at a site's root.
  159. ## Features
  160. - 📂 **Scan**: Analyze the repository for CI/CD enhancement suggestions, including security services and best practices.
  161. - 🔍 **CI Analysis**: Grades whether each control can actually fail a build, not only whether it is present.
  162. - 🛠️ **Fix**: Prints, or writes as a workflow, CI configuration for the categories a scan reports as missing.
  163. - 🚀 **Open Source**: Contributions are welcome to enhance Zanadir's capabilities!
  164. ## Supported CI Actions
  165. Zanadir currently supports:
  166. - GitHub Actions
  167. - CircleCI
  168. - GitLab
  169. - Bitbucket Pipelines
  170. - Azure Pipelines
  171. - Jenkins
  172. Future work will include support for:
  173. - Tekton
  174. ## Categories We Suggest
  175. Zanadir analyzes repositories in the following categories. The name in bold is
  176. the exact value to pass to `--excluded-categories` (matching is
  177. case-insensitive):
  178. - 🛡️ **SCA**: Software Composition Analysis
  179. - 🔐 **Secrets Detection**: Secrets Management
  180. - 📜 **License Compliance**: License Compliance
  181. - 🛠️ **End Of Life**: End-of-Life Software Packages
  182. - 📊 **Coverage**: Test Coverage
  183. - 📊 **Performance Testing**: Test Performance and Reliability
  184. - 🧑‍💻 **Linter**: Code Linting
  185. - 🧪 **Unit Tests**: Automated Unit Testing
  186. - 🔎 **SAST**: Static Application Security Testing
  187. - 🏗️ **IaC Security**: Infrastructure-as-Code Misconfiguration Scanning
  188. - 🔗 **Supply Chain**: SBOM Generation, Signing and Provenance
  189. - 🧱 **Workflow Security**: Hardening of the pipeline definition itself
  190. - 🤖 **Agent Skill Security**: Scanning agent skills (`SKILL.md`) for prompt injection and malicious code
  191. ## Usage Examples
  192. ### Basic Usage
  193. Scan a repository for CI/CD improvement suggestions:
  194. ```sh
  195. zanadir scan --dir /path/to/your/repo
  196. ```
  197. Or scan a GitHub repository without cloning it:
  198. ```sh
  199. zanadir scan --repo github.com/owner/name
  200. zanadir scan --repo owner/name@v2.0.0 # a branch, tag or commit
  201. zanadir fix --repo owner/name
  202. ```
  203. `--repo` lists the repository's files at one commit and downloads only the
  204. ones zanadir reads (CI and build files, plus the start of JSON files for
  205. infrastructure detection) into a temporary directory. Every other file is an
  206. empty placeholder, since only its name matters. It then scans the directory
  207. exactly as a checkout and removes it. That is a handful of GitHub API
  208. requests per scan, however large the repository. The API also shows what no
  209. file does: workflows GitHub has turned off, which then count for nothing, and
  210. code scanning's default setup, which counts as the CodeQL workflow it runs,
  211. for the languages of its latest run. A scan of a checkout can't see it. A repository too large to list in one
  212. request is downloaded as an archive instead. Public repositories need no
  213. token; set `GITHUB_TOKEN` (or `GH_TOKEN`) to reach private ones or raise
  214. GitHub's rate limit of 60 requests an hour without one. GitLab and Bitbucket
  215. repositories still need a clone.
  216. ### Output Formats
  217. Zanadir supports three output formats: table (default), JSON and SARIF.
  218. #### Table Output (Default)
  219. ```sh
  220. zanadir scan --dir . --output table
  221. ```
  222. **Sample Output:**
  223. ```
  224. Coverage 10/11 - 1 category needs attention:
  225. |--------------------------------|--------------------------------|-------------------|
  226. | CATEGORY | DESCRIPTION | SUGGESTED TOOLS |
  227. |--------------------------------|--------------------------------|-------------------|
  228. | Performance and Reliability | Tools for load, stress and | k6, JMeter, |
  229. | Testing Tools | reliability testing, to verify | Gatling, Apache |
  230. | | a system holds up under | Bench, Artillery, |
  231. | | expected and peak traffic. | BlazeMeter |
  232. |--------------------------------|--------------------------------|-------------------|
  233. 10 categories are covered by:
  234. SCA Dependabot, govulncheck
  235. Secrets Detection Gitleaks (advisory)
  236. Linter golangci-lint
  237. Unit Tests go test
  238. ...
  239. ```
  240. The covered categories come last, each with the tools found for it. A tool
  241. whose run cannot block a merge shows its grade (see
  242. [Effectiveness](#effectiveness)). A rule that covers several
  243. tools, such as the test command one, names the one it matched: `pytest`,
  244. `go test` or `mvn`.
  245. When nothing is missing, the scan says so rather than printing an empty table,
  246. and lists what covers each category:
  247. ```
  248. Coverage 11/11 - all categories are covered.
  249. 11 categories are covered by:
  250. ...
  251. ```
  252. The headline is bold on an interactive terminal. Colour is omitted when the
  253. output is piped or written with `--output-file`, and when `NO_COLOR` is set.
  254. #### JSON Output
  255. ```sh
  256. zanadir scan --dir . --output json
  257. ```
  258. One object with the score, the CI systems whose configuration was found, the
  259. uncovered categories and the tools that cover them, the covered categories whose tooling cannot fully protect the
  260. repository, the categories left out of the score, and every covered category
  261. with the tools found for it. Every list is an array, empty rather than `null`
  262. when there is nothing in it.
  263. ```json
  264. {
  265. "score": { "covered": 4, "total": 11 },
  266. "platforms": ["github"],
  267. "uncovered": [
  268. {
  269. "id": "Secrets Detection",
  270. "name": "Data Leakage & Secrets Detection",
  271. "description": "Tools that help detect sensitive information ...",
  272. "suggestions": [
  273. {
  274. "name": "Gitleaks",
  275. "repository": "https://github.com/gitleaks/gitleaks",
  276. "description": "..."
  277. }
  278. ]
  279. }
  280. ],
  281. "weakened": [
  282. { "category": "SCA", "verdict": "advisory", "location": ".github/dependabot.yml" }
  283. ],
  284. "notApplicable": ["IaC Security"],
  285. "covered": [
  286. {
  287. "category": "SCA",
  288. "verdict": "advisory",
  289. "tools": [
  290. { "name": "Dependabot", "verdict": "advisory", "locations": [".github/dependabot.yml"] }
  291. ]
  292. }
  293. ]
  294. }
  295. ```
  296. In `covered`, a category's `verdict` is its strongest tool's, and each tool
  297. has its own with the files it runs in. Tools are listed strongest first.
  298. `language` appears on a suggested tool only when it is specific to one
  299. language, and `location` on a weakened category only when it points inside
  300. the repository. Before 0.10.0, `--output json` printed only the bare array that
  301. is now `uncovered`, with capitalised keys.
  302. #### SARIF Output
  303. ```sh
  304. zanadir scan --dir . --output sarif
  305. ```
  306. SARIF is the standard interchange format for static analysis results. Emitting
  307. it lets uncovered categories show up in GitHub's Security tab, and in any other
  308. SARIF-consuming platform, alongside your other scanners.
  309. Each uncovered category becomes one SARIF rule and one result at `warning`
  310. level, with the suggested tools listed in the result's help text. Results are
  311. anchored at a CI configuration file — the place the missing tool would be
  312. added. A missing control is not a defect on a particular line, but every SARIF
  313. consumer expects a location, and GitHub code scanning rejects a report whose
  314. results have none.
  315. #### Markdown Output
  316. ```sh
  317. zanadir scan --dir . --output markdown
  318. ```
  319. Markdown is the format for putting a scan in front of people rather than in a
  320. file. Tools link to their repositories, and the report opens with a hidden
  321. marker so a workflow can update the comment it posted last time instead of
  322. adding a new one on every push.
  323. **Sample Output:**
  324. ```markdown
  325. <!-- zanadir-report -->
  326. ### zanadir
  327. Coverage 10/11 - 1 category needs attention:
  328. | Category | Description | Suggested tools |
  329. | --- | --- | --- |
  330. | Performance and Reliability Testing Tools | Tools for load, stress and reliability testing. | [k6](https://github.com/grafana/k6), [JMeter](https://github.com/apache/jmeter) |
  331. ```
  332. When nothing is missing the table is omitted, leaving a single line.
  333. #### Writing the report to a file
  334. Use `--output-file` to write the report to a path instead of stdout. This works
  335. with every format, and is the reliable way to produce a machine-readable report:
  336. redirecting stdout captures the debug log as well, so `--output sarif --debug >
  337. report.sarif` yields a file that is not valid JSON.
  338. ```sh
  339. zanadir scan --dir . --output sarif --output-file zanadir.sarif
  340. ```
  341. To publish the report from a GitHub Actions workflow:
  342. ```yaml
  343. - name: Run zanadir
  344. run: zanadir scan --dir . --output sarif --output-file zanadir.sarif
  345. - name: Upload SARIF
  346. uses: github/codeql-action/upload-sarif@v3
  347. with:
  348. sarif_file: zanadir.sarif
  349. ```
  350. Uncovered categories then appear in the repository's **Security** tab alongside
  351. your other scanners.
  352. ### Posting the report to a pull request
  353. SARIF puts uncovered categories in the **Security** tab, which people visit
  354. occasionally. A pull request comment is where they already are.
  355. ```yaml
  356. permissions:
  357. contents: read
  358. pull-requests: write
  359. steps:
  360. - name: Run zanadir
  361. run: zanadir scan --dir . --output markdown --output-file zanadir.md
  362. - name: Post the report
  363. run: gh pr comment "$NUMBER" --body-file zanadir.md --edit-last --create-if-none
  364. env:
  365. GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  366. NUMBER: ${{ github.event.pull_request.number }}
  367. ```
  368. `--edit-last` keeps one comment up to date instead of adding one per push. It
  369. matches on the last comment by the same user, so if something else comments as
  370. `github-actions` too, match the marker instead:
  371. ```yaml
  372. - name: Find the previous report
  373. uses: peter-evans/find-comment@v4
  374. id: previous
  375. with:
  376. issue-number: ${{ github.event.pull_request.number }}
  377. body-includes: "<!-- zanadir-report -->"
  378. - name: Post the report
  379. uses: peter-evans/create-or-update-comment@v5
  380. with:
  381. comment-id: ${{ steps.previous.outputs.comment-id }}
  382. issue-number: ${{ github.event.pull_request.number }}
  383. body-path: zanadir.md
  384. edit-mode: replace
  385. ```
  386. A pull request from a fork gets a read-only token, so the comment step cannot
  387. post. Guard it with
  388. `if: github.event.pull_request.head.repo.full_name == github.repository`
  389. rather than reaching for `pull_request_target`, which would run your workflow
  390. with write access to a fork's code.
  391. ## Coverage Score
  392. Every scan is summarised as a coverage score: the categories that apply to the
  393. repository, minus the ones still uncovered.
  394. Three rules keep the number honest:
  395. - **Excluded categories leave the denominator.** A repository is not marked
  396. down for a category it has declared irrelevant with `--excluded-categories`.
  397. - **So do categories with nothing to scan.** A repository with no Terraform,
  398. Helm chart, Kubernetes manifest or Dockerfile is not told to add Checkov,
  399. and is scored out of ten rather than eleven. The scan says which:
  400. ```
  401. IaC Security is not applicable and is out of the score: nothing in this
  402. repository needs it.
  403. ```
  404. Three categories are ruled out this way. **IaC Security** needs
  405. infrastructure to scan, and the detection is deliberately broad — a
  406. directory called `infra`, `k8s` or `charts` is enough to keep it.
  407. **Workflow Security** needs GitHub Actions or GitLab CI, the formats its
  408. tools read. A GitLab project is pointed at glsec or poutine, a GitHub one at
  409. zizmor, actionlint, Scorecard or poutine, and a CircleCI-only repository is
  410. not scored on it. **Agent Skill Security** needs a `SKILL.md` outside
  411. dependency and test directories; it is credited for Cisco Skill Scanner,
  412. SkillSpector or Snyk Agent Scan run in CI. To check the skills themselves,
  413. see [`zanadir skills`](#zanadir-skills).
  414. The rest apply to any codebase, and the ones that arguably do not — load
  415. testing a library, an SBOM for something that ships nothing — cannot be told
  416. apart from the ones that do, so guessing would rule out categories a
  417. repository does need.
  418. - **Baseline-accepted gaps still count as uncovered.** A baseline records that
  419. a gap is tolerated, not that it was closed. A score that rose because someone
  420. committed a file would measure nothing.
  421. ### README Badge
  422. `--badge` writes the score as a [shields.io endpoint][shields] file:
  423. ```sh
  424. zanadir scan --dir . --badge zanadir-badge.json
  425. ```
  426. ```json
  427. {
  428. "schemaVersion": 1,
  429. "label": "zanadir",
  430. "message": "10/11",
  431. "color": "green"
  432. }
  433. ```
  434. Publish that file from CI and point a badge at it. Put it on a branch of its
  435. own rather than committing it to the default branch: a protected default
  436. branch only takes changes through a pull request, so a workflow that pushes
  437. the badge there is rejected.
  438. ```markdown
  439. ![zanadir](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/badges/zanadir-badge.json)
  440. ```
  441. A job that keeps it current on every push to the default branch, publishing
  442. to a `badges` branch it creates on the first run:
  443. ```yaml
  444. badge:
  445. if: github.event_name == 'push'
  446. runs-on: ubuntu-latest
  447. permissions:
  448. contents: write
  449. steps:
  450. - uses: actions/checkout@v7
  451. - name: Run zanadir
  452. run: zanadir scan --dir . --badge zanadir-badge.json
  453. - name: Publish the badge when it moved
  454. run: |
  455. set -euo pipefail
  456. cp zanadir-badge.json "$RUNNER_TEMP/zanadir-badge.json"
  457. rm -f zanadir-badge.json
  458. git config user.name github-actions
  459. git config user.email github-actions@github.com
  460. if git fetch --depth=1 origin badges 2>/dev/null; then
  461. git switch --discard-changes -C badges FETCH_HEAD
  462. else
  463. git switch --orphan badges
  464. fi
  465. cp "$RUNNER_TEMP/zanadir-badge.json" zanadir-badge.json
  466. git add zanadir-badge.json
  467. if git diff --cached --quiet; then exit 0; fi
  468. git commit -m "chore: update zanadir badge"
  469. git push origin badges
  470. ```
  471. The `badges` branch holds that one file and nothing else. If a ruleset
  472. covers every branch rather than only the default one, exclude `badges` from
  473. it.
  474. The colour tracks the score: green at 80% or above, yellow at 60%, orange at
  475. 40%, red below that, and bright green only at full coverage.
  476. [shields]: https://shields.io/badges/endpoint-badge
  477. ## Effectiveness
  478. Presence is not protection. A scanner wired up so it can never fail a build
  479. leaves a repository worse off than one with no scanner at all, because
  480. everybody believes the control is there. All of these used to report
  481. **covered**:
  482. ```yaml
  483. - uses: gitleaks/gitleaks-action@v2
  484. continue-on-error: true # the job stays green whatever it finds
  485. ```
  486. ```yaml
  487. on:
  488. schedule: [{cron: "0 3 * * *"}] # nothing is blocked at merge time
  489. ```
  490. ```yaml
  491. on:
  492. push: {branches: [main]} # pull requests are never checked
  493. ```
  494. A scan now grades each control it finds and reports the ones that protect less
  495. than their presence suggests:
  496. ```
  497. 3 covered categories are weakened:
  498. Linter is partial (.github/workflows/pushonly.yml)
  499. SCA is advisory (.github/workflows/nightly.yml)
  500. Secrets Detection is advisory (.github/workflows/ci.yml)
  501. ```
  502. | Verdict | Meaning |
  503. |---|---|
  504. | `enforcing` | the control can fail the build on the path that gates a change |
  505. | `partial` | it can fail a build, but not on that path, or cannot check everything it should |
  506. | `advisory` | it runs, and cannot block anything |
  507. | `unknown` | the configuration cannot be read well enough to say |
  508. A `pull_request` trigger gates only if it runs on the change itself and on
  509. pull requests to the default branch. `types: [closed]` runs after the merge,
  510. so it grades like a push. A `branches:` or `branches-ignore:` filter that
  511. leaves out the default branch makes the control `unknown`. The default branch
  512. is set outside the repository: zanadir reads it from the checkout's
  513. `origin/HEAD`, which `git clone` sets, from GitHub with `--repo` or
  514. `--required-checks`. Where none of those has it, as in most CI checkouts,
  515. `main`, `master`, `trunk` and `develop` stand in for it, or whichever of them
  516. the filter names.
  517. Supply Chain is graded against a different path. An SBOM, a signature or a
  518. provenance attestation describes what ships rather than looking for something
  519. to block, so it belongs where the artifact is published: running on a release,
  520. a push, a tag, a pull request or a workflow chained after one is `enforcing`.
  521. A manual run may be the release itself, which the file cannot tell, so it is
  522. `unknown`. Only a schedule, detached from anything that ships, is `advisory`,
  523. and `continue-on-error` is `advisory` here as everywhere: a signing step that
  524. can fail silently publishes unsigned artifacts.
  525. SCA is also held to the repository's detected ecosystems. If an enforcing
  526. language-specific scanner leaves another detected language without an enforcing
  527. SCA check, the category is `partial`, with the gap explained:
  528. ```
  529. SCA is partial (.github/workflows/ci.yml): govulncheck checks only Go; Python dependencies detected from repository manifests have no enforcing SCA check
  530. ```
  531. This uses the same root and immediate-subdirectory manifests and directory
  532. skips as [language detection](#language-aware-suggestions), including a
  533. `package.json` used only for tooling. Manifest contents are not inspected,
  534. except that a `pyproject.toml` declaring no dependencies (one that only
  535. configures a linter, say) names no Python packages to scan.
  536. Enforcing tools combine their ecosystem coverage: a Go scanner and a Python
  537. scanner can cover both languages together. An enforcing multi-ecosystem scanner
  538. continues to cover them, while advisory dependency bots do not close a gap.
  539. Only the category verdict changes; individual tool grades stay as reported.
  540. Existing reasons for weakened controls still apply.
  541. A dependency scanner also looks packages up
  542. by name and version, so one that `uv.lock` or `package-lock.json` installs from
  543. a git repository or a direct URL is invisible to every scanner, and an
  544. enforcing SCA control in a repository with such a package is `partial`, with
  545. the packages named:
  546. ```
  547. SCA is partial (.github/workflows/ci.yml): uv.lock installs en-core-web-sm from a git or URL source, which no dependency scanner can look up
  548. ```
  549. A registry other than PyPI or npm's does not count, since a mirror or proxy
  550. serves their packages under the same names, and `path`, `directory`,
  551. `editable`, `file:` and linked sources are the repository's own code. Only the
  552. lockfiles at the repository root are read.
  553. SAST is held to the detected languages too, more loosely. A CodeQL run whose
  554. `languages` (or `--language`) names none of them, among those CodeQL analyses,
  555. is `partial`:
  556. ```
  557. SAST is partial (.github/workflows/codeql.yml): CodeQL analyses only actions, python; the Java, Rust code detected from repository manifests is not scanned
  558. ```
  559. One analysed language is enough, since a manifest can be there only for
  560. tooling. A language CodeQL can't analyse, such as PHP, doesn't count against
  561. it, and one zanadir doesn't detect (`c-cpp`, `swift`) or can't read (a matrix
  562. expression) counts as covering the code. Kotlin's Gradle build is detected as
  563. Java, which `java-kotlin` covers.
  564. A weakened control does not fail a scan unless you ask it to. `--enforce` and
  565. `--fail-on` act only on categories with no tooling; `--fail-on-weakened` is
  566. what turns a weak control into a failure:
  567. ```sh
  568. zanadir scan --dir . --fail-on-weakened
  569. ```
  570. ```
  571. Enforcement failed: controls that cannot fail a build: Secrets Detection (advisory)
  572. ```
  573. The two are independent. `--enforce` on its own still ignores weakened
  574. controls, so upgrading does not start failing builds that passed before.
  575. `--fail-on` narrows both.
  576. A baseline accepts a weakness **at the verdict it had when accepted**:
  577. ```yaml
  578. version: 1
  579. categories:
  580. - Performance Testing
  581. weakened:
  582. Secrets Detection: partial
  583. ```
  584. So accepting `partial` does not also accept it becoming `advisory` later. If
  585. the control gets worse than its recorded verdict, the scan fails again.
  586. `--write-baseline` records the verdicts for you.
  587. Some of this is generic. `continue-on-error` defeats any control, and so do
  588. its shell spellings: `gitleaks detect || true`, `|| echo failed`, and running
  589. the tool as the condition of an `if` or a `!`. A `|| exit 1` that fails again
  590. is fine. So does a workflow that only runs on a schedule. The rest is specific
  591. to one tool, and a rule can say so:
  592. ```yaml
  593. - id: "tfsec-rule"
  594. regex: "(?i)\\btfsec\\b"
  595. weakenedWhen:
  596. - runMatches: "--soft-fail\\b"
  597. verdict: "advisory"
  598. - input: "soft_fail"
  599. equals: "true"
  600. verdict: "advisory"
  601. ```
  602. A check is either a regex over the step's shell command or one action input
  603. compared to a value - deliberately not an expression language. Covered today:
  604. `gitleaks --exit-code 0`, `tfsec` and `checkov` `--soft-fail` /
  605. `soft_fail: true`, and `anchore/scan-action` with `fail-build: false`.
  606. Some tools are the other way round: they exit 0 on findings unless told to
  607. fail. `trivy` without `--exit-code 1` (including `trivy-action` without
  608. `exit-code`), `grype` without `--fail-on`, `kubescape` without a severity or compliance
  609. threshold (its old `--fail-threshold` is ignored by current releases, so it is
  610. `unknown`),
  611. `semgrep scan` without `--error` and `trufflehog` without `--fail` only report,
  612. so they are `advisory`. When the repository has a config file the tool reads
  613. by default, such as `trivy.yaml` or `.grype.yaml`, or the step names one with
  614. `--config`, the file may set it, and the control is `unknown`:
  615. ```yaml
  616. exitsZeroUnless:
  617. runMatches: "--fail-on\\b" # what makes it fail
  618. unknownWhen: "--config\\b" # what may, out of sight
  619. configFiles: [".grype.yaml"] # read from the repository by default
  620. ```
  621. For actions that take flags through an input, `exitsZeroUnless` can name it.
  622. The flawfinder action, for example, uses:
  623. ```yaml
  624. exitsZeroUnless:
  625. input: "arguments"
  626. runMatches: "--error-level\\b"
  627. ```
  628. Matched shell commands are checked first. If none match and the step matches
  629. by its action, the named input is checked instead. Flawfinder with missing or
  630. empty `arguments`, or with only `--sarif ./`, is `advisory`; `--error-level=4`
  631. lets the normal triggers decide its grade. An input set by an expression such
  632. as `${{ inputs.args }}` is `unknown`, even if the expression mentions the flag.
  633. zanadir cannot see an exit code set in a workflow's `env:`, such as
  634. `TRIVY_EXIT_CODE`, so such a step reads as `advisory`.
  635. Two deliberate silences. An `if:` condition is never interpreted, because it
  636. can reference arbitrary context and reading one wrong is worse than admitting
  637. it cannot be read - the control is reported `unknown` instead. And a category
  638. is judged by its strongest control, so one properly wired scanner keeps the
  639. category quiet however many weak ones sit beside it.
  640. ### Required checks
  641. A scanner can run on every pull request and still block nothing, because its
  642. check is not required to merge. That lives in the repository's rulesets and
  643. branch protection, not its files, so it is opt-in:
  644. ```sh
  645. zanadir scan --dir . --required-checks
  646. zanadir scan --repo owner/name --required-checks
  647. ```
  648. zanadir reads the default branch's required checks from GitHub (public
  649. repositories need no token; `GITHUB_TOKEN` or `GH_TOKEN` is used if set). A
  650. GitHub Actions control that would be `enforcing` stays so only when its job's
  651. check is required, matrix (`build (ubuntu-latest)`) and reusable-workflow
  652. (`codeql / Analyze`) names included; otherwise it is `partial`. A ruleset
  653. that blocks merges on a tool's code scanning alerts counts too: a scanner that
  654. runs on every pull request and uploads to code scanning is `enforcing` even
  655. when its own step only reports, such as `trivy-action` writing SARIF without
  656. `exit-code`:
  657. ```
  658. 2 covered categories are weakened:
  659. SAST is partial (.github/workflows/codeql.yml): its check is not required to merge
  660. Secrets Detection is partial (.github/workflows/secrets.yml): its check is not required to merge
  661. Merge settings for main:
  662. Required to merge: build (ubuntu-latest), build (macos-latest).
  663. Problem: ruleset "checks must pass" requires "Run tests" but applies to no branch.
  664. ```
  665. It also names settings that look like protection and are not: a ruleset that
  666. requires checks but targets no branch or only evaluates, and a required
  667. GitHub Actions check that no workflow job reports. Checks other apps report,
  668. such as DCO, are never judged. If the settings cannot be read, the scan warns
  669. and grades without them. Only GitHub is read; on other platforms the merge
  670. settings are still outside what zanadir can see.
  671. ### Controls declared outside the pipeline
  672. Dependabot and Renovate are detected from their configuration -
  673. `.github/dependabot.yml`, `renovate.json` and the other names Renovate
  674. accepts - not from a CI job, because that is not where they live.
  675. They are graded `advisory`. Both run on the forge's own schedule and open pull
  676. requests; neither can fail a build. So a repository whose only dependency
  677. control is Dependabot is reported as covered **and** weakened, which is a more
  678. useful answer than either "you have no SCA" or "you are covered":
  679. ```
  680. 1 covered category is weakened:
  681. SCA is advisory (.github/dependabot.yml)
  682. ```
  683. ### Platform coverage
  684. GitHub Actions is graded in full. GitLab CI is graded for the two signals that
  685. are unambiguous there - `allow_failure: true`, which is `continue-on-error`
  686. under another name, and `when: manual`, a job that only runs when somebody
  687. asks.
  688. GitLab's `include:` is followed. A local file (`local:` or a bare path,
  689. wildcards allowed) is read as more of the same configuration. GitLab's own
  690. templates and CI/CD components cannot be read from the repository, so they are
  691. recognised by name: `Jobs/SAST.gitlab-ci.yml` or
  692. `components/sast/sast@...` counts as SAST, and likewise for Secret Detection,
  693. Dependency and Container Scanning, SAST-IaC, License Scanning, Code Quality and
  694. the performance-testing templates. A `project:` or `remote:` include is
  695. skipped. A job zanadir cannot read is skipped rather than failing the scan.
  696. GitLab's `rules:`, `only:` and `except:` are deliberately not interpreted.
  697. Whether a branch pipeline gates a merge depends on a project setting that is
  698. not in the repository, so reading them would be guessing. A GitLab job with
  699. neither weakening field is reported `unknown`, which says nothing rather than
  700. something wrong. CircleCI has no equivalent signal and is not graded.
  701. Bitbucket Pipelines splits its file by trigger, so most of it is graded:
  702. | Where the tool runs | Verdict |
  703. | --- | --- |
  704. | `pull-requests:` | `enforcing` |
  705. | `branches:` for one named branch, such as `main` | `partial` - it runs after the merge |
  706. | `tags:`, `custom:`, or a step or stage with `trigger: manual` | `advisory` |
  707. | `after-script:` | `advisory` - a failing after-script does not fail the step |
  708. | `default:`, or a wildcard branch pattern | `unknown` |
  709. `default:` also runs on a pull request's source branch, and whether that build
  710. blocks the merge is a merge check configured outside the repository, so it is
  711. left `unknown` for the same reason as GitLab's branch pipelines. Pipes are read
  712. like GitHub actions: `pipe: snyk/snyk-scan` counts as Snyk, and
  713. `DONT_BREAK_BUILD: "true"` grades it `advisory`.
  714. A Jenkinsfile (and variants beside it such as `Jenkinsfile.release`) is read
  715. as Groovy tokens, not run. `sh`, `bat` and `powershell` steps are read like
  716. `run:`, and other steps such as `snykSecurity`, `dependencyCheck`,
  717. `withSonarQubeEnv` or `junit` like actions, with their named arguments as
  718. inputs. Which branches and pull requests build is configured on the Jenkins
  719. job, not in the file, so a control is `unknown` unless the file itself
  720. weakens it:
  721. | In the Jenkinsfile | Verdict |
  722. | --- | --- |
  723. | inside `catchError(buildResult: 'SUCCESS')` or `buildResult: null` | `advisory` - the build stays green |
  724. | a step option such as `snykSecurity(failOnIssues: false)` or `waitForQualityGate abortPipeline: false` | `advisory` |
  725. | inside `when { }`, `if`, `warnError` or `catchError(buildResult: 'UNSTABLE')`, or `sh(returnStatus: true)` | `unknown` |
  726. A shared-library step configured only by assignments, such as
  727. `mavenBuild { dependencyCheck = 'enabled' }`, cannot be read.
  728. Azure Pipelines is read from `azure-pipelines.yml` (or `.yaml`) at the
  729. repository root, following `template:` and `extends:` references to files in
  730. the same repository. A template in another repository (`path@alias`) or one
  731. named by an expression cannot be read and is skipped.
  732. | Where the tool runs | Verdict |
  733. | --- | --- |
  734. | a pipeline whose `pr:` names branches | `enforcing` |
  735. | `continueOnError: true` on the step or its job | `advisory` |
  736. | `trigger: none`, `pr: none` and only `schedules:` | `advisory` |
  737. | any `condition:` other than `succeeded()` | `unknown` |
  738. | a pipeline with no `pr:` | `unknown` |
  739. With no `pr:`, an Azure Repos pull request is validated by a branch policy
  740. outside the repository, so the file cannot say whether the pipeline gates it.
  741. `succeeded()` is ignored because it is the default every step already has. A
  742. step with `enabled: false` never runs and counts for nothing. Tasks are read
  743. like actions, with `inputs:` as their inputs, so `SnykSecurityScan` with
  744. `failOnIssues: false` grades `advisory`.
  745. In SARIF a weakened control is a `note`, pointing at the file that produced
  746. the verdict, while a missing category stays a `warning`.
  747. ## Language-Aware Suggestions
  748. Zanadir detects which languages a repository uses and suggests only tools that
  749. apply to it — a Go project is not offered ESLint, and a JavaScript project is
  750. not offered Pylint. Tools that work regardless of ecosystem (Trivy, Gitleaks,
  751. Codecov, and so on) are always suggested.
  752. Detection is based on dependency manifests in the repository root and its
  753. immediate subdirectories, so common monorepo layouts work:
  754. | Language | Detected from |
  755. |------------|------------------------------------------------------------|
  756. | Go | `go.mod` |
  757. | Python | `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` |
  758. | JavaScript | `package.json` |
  759. | Ruby | `Gemfile`, `*.gemspec` |
  760. | Java | `pom.xml`, `build.gradle`, `build.gradle.kts` |
  761. | Rust | `Cargo.toml` |
  762. | PHP | `composer.json` |
  763. | C# | `*.csproj`, `*.sln` |
  764. `node_modules`, `vendor` and other dependency directories are skipped, since
  765. their manifests describe code the project did not write. If no language is
  766. recognised, every tool is suggested, exactly as before.
  767. ### Advanced Usage
  768. #### Exclude Specific Categories
  769. Skip certain categories during analysis:
  770. ```sh
  771. zanadir scan --dir . --excluded-categories "SCA,Secrets Detection"
  772. ```
  773. Category names must match the list above. An unrecognized name is rejected with
  774. an error rather than being silently ignored.
  775. #### Enforce Mode
  776. Zanadir provides an `--enforce` flag to ensure that all CI/CD suggestions are fulfilled. If any suggestion is not met, the CI pipeline will fail. This helps enforce security best practices and compliance in automated workflows.
  777. ```sh
  778. zanadir scan --dir . --enforce
  779. ```
  780. The category that failed the build is printed to stderr:
  781. ```
  782. Enforcement failed: uncovered categories: SCA, Secrets Detection
  783. ```
  784. Exit codes: `0` when the scan passes, `1` when enforcement fails or the scan
  785. cannot run (an unreadable directory or configuration), and `2` for a command
  786. line zanadir does not understand, such as a mistyped flag. A typo therefore
  787. fails the build instead of passing it with nothing enforced.
  788. #### Failing on Specific Categories
  789. `--enforce` is all-or-nothing, which makes it hard to adopt on an existing
  790. repository: a single uncovered category fails every build. Use `--fail-on` to
  791. enforce only the categories you care about, while the rest stay informational:
  792. ```sh
  793. zanadir scan --dir . --fail-on "SCA,Secrets Detection"
  794. ```
  795. `--fail-on` implies enforcement, so `--enforce` is not needed alongside it.
  796. Category names are matched case-insensitively.
  797. #### Baseline
  798. A baseline records the gaps a repository knowingly accepts. Those categories
  799. are still reported, but they no longer fail a scan — so enforcement can be
  800. switched on before everything is fixed, and only *new* gaps break the build.
  801. Generate one from the current state:
  802. ```sh
  803. zanadir scan --dir . --write-baseline
  804. ```
  805. This writes `.zanadir-baseline.yaml` (override with `--baseline <path>`) and
  806. exits successfully:
  807. ```yaml
  808. # zanadir baseline: categories that are uncovered but accepted.
  809. # These are still reported; they just do not fail a scan.
  810. # Regenerate with: zanadir scan --dir . --write-baseline
  811. version: 1
  812. categories:
  813. - Coverage
  814. - Performance Testing
  815. ```
  816. Then enforce against it. The scan passes while the repository's gaps match the
  817. baseline, and fails as soon as a new one appears:
  818. ```sh
  819. zanadir scan --dir . --enforce --baseline .zanadir-baseline.yaml
  820. ```
  821. Commit the baseline so the accepted gaps are reviewable, and shrink it over
  822. time.
  823. #### Debug Mode
  824. Get detailed logging information:
  825. ```sh
  826. zanadir scan --dir . --debug
  827. ```
  828. #### Config File
  829. `--config` (`-c`) reads flag values from a YAML file, so a team stops
  830. repeating them on every invocation. Each key is the name of the flag it sets:
  831. ```yaml
  832. # .zanadir.yml
  833. excluded-categories: [Performance Testing]
  834. enforce: true
  835. fail-on-weakened: true
  836. required-checks: true
  837. baseline: .zanadir-baseline.yaml
  838. badge: zanadir-badge.json
  839. output: markdown
  840. ```
  841. ```sh
  842. zanadir scan --dir . -c .zanadir.yml
  843. zanadir scan --dir . -c .zanadir.yml --output json # the command line wins
  844. ```
  845. - A flag given on the command line overrides the same key in the file.
  846. - An unknown key is an error, so a misspelt `exclude-categories` fails the
  847. scan instead of silently scanning without the exclusion.
  848. - Relative paths (`baseline`, `badge`, `output-file`) are resolved against the
  849. directory holding the config file, not the directory you run from.
  850. - `zanadir fix -c` reads the same file and uses only `excluded-categories` and
  851. `debug`.
  852. - `dir` and `write-baseline` stay on the command line: one says what to scan,
  853. the other is a one-off action rather than a setting.
  854. #### Custom Rules
  855. zanadir only recognises the tools in its catalogue, so an in-house scanner
  856. reads as a missing category. Teach it with `rules:` in the config file, in the
  857. same shape as the [built-in rules](rules/storage):
  858. ```yaml
  859. rules:
  860. - id: acme-scan
  861. name: Acme Scan # optional: the tool the report names; without it, the matched text
  862. applyOn: [Job.Run] # Artifact.Name, Job.Name, Job.Package, Job.Run, Job.Env
  863. categories: [SAST]
  864. regex: '\bacme-scan\b'
  865. unless: '--list-rules' # optional: a match that does not count, e.g. a command that does not scan
  866. weakenedWhen: # optional: configurations that cannot fail a build
  867. - runMatches: '--report-only'
  868. verdict: advisory # advisory or partial
  869. exitsZeroUnless: # optional, for a tool that only reports by default
  870. runMatches: '--fail' # the flag that makes it fail
  871. ```
  872. A custom SCA rule can declare which ecosystems it checks:
  873. ```yaml
  874. rules:
  875. - id: acme-go-audit
  876. name: Acme Go Audit
  877. applyOn: [Job.Run]
  878. categories: [SCA]
  879. regex: '\bacme-go-audit\b'
  880. ecosystems: [Go]
  881. ```
  882. `ecosystems` accepts the canonical names `Go`, `Python`, `JavaScript`, `Ruby`,
  883. `Java`, `Rust`, `PHP` and `C#`. Omitting it or setting an empty list leaves
  884. coverage unrestricted. It affects SCA coverage only; other categories keep
  885. their existing behavior.
  886. A rule for a tool that takes `--language=a,b` can map each name to the
  887. canonical languages it analyses, as the CodeQL rule does. A run that names
  888. none of the repository's languages that the map covers is `partial`; a name
  889. the map leaves out counts as covering the code, and an empty list
  890. (`actions: []`) as covering none of it:
  891. ```yaml
  892. languages:
  893. actions: []
  894. java-kotlin: [Java]
  895. python: [Python]
  896. ```
  897. A rule that also matches on `Artifact.Name` can take `unlessPackage`, a regex
  898. over the workflow's actions: when one matches, the workflow's steps decide and
  899. its name does not count (`unlessPackage: '^acme/scan-action'`).
  900. An `exitsZeroUnless` with `input` requires `Job.Package` in `applyOn`; it may
  901. also include `Job.Run` to grade direct commands. Without `input`, it requires
  902. `Job.Run`. The `runMatches` regex is required in either case.
  903. A command's executable is matched by its unquoted basename: `"$RUNNER_TEMP/grant" check`
  904. is recognised as `grant check`. Arguments keep their quoting, and the original
  905. command is retained as evidence. Custom command rules use the same normalization.
  906. Custom rules add to the catalogue and never replace a built-in rule, so an
  907. `id` that is already taken is an error, as is a regex that does not compile or
  908. an unknown category. A rule that matches counts as coverage and is graded like
  909. any other, so `--fail-on-weakened` catches `acme-scan --report-only` too.
  910. `zanadir fix` uses the same rules to decide what is uncovered.
  911. #### Complete Example
  912. ```sh
  913. # Scan with all options
  914. zanadir scan \
  915. --dir /path/to/repo \
  916. --output json \
  917. --excluded-categories "Linter" \
  918. --enforce \
  919. --debug
  920. ```
  921. ## `zanadir fix`
  922. A scan tells you what is missing. `fix` prints the configuration to add:
  923. ```sh
  924. zanadir fix --dir .
  925. ```
  926. ```
  927. Infrastructure as Code Security is not covered. Add to .github/workflows/security.yml:
  928. - name: Scan infrastructure as code
  929. uses: bridgecrewio/checkov-action@v12
  930. with:
  931. directory: .
  932. https://github.com/bridgecrewio/checkov
  933. ```
  934. It prints only; no file is touched. The CI platform is detected from the
  935. repository, and snippets are emitted for GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure Pipelines or Jenkins
  936. accordingly.
  937. Not every suggested tool has a template, and some templates need a file the
  938. repository may not have: the end-of-life check builds an image from a
  939. `Dockerfile`, and the load test runs a `load-test.js` written for the service.
  940. `fix` emits nothing half-right. A category it cannot fill is listed at the end
  941. with the reason, and with the exclusion to use when the category does not
  942. apply:
  943. ```
  944. Not covered, with no snippet that fits:
  945. End-of-Life Package Checkers: Trivy checks a container image, and there is no Dockerfile at the repository root to build one. If it does not apply here, exclude it with -e "End Of Life".
  946. ```
  947. Coverage snippets set a floor the test run enforces itself
  948. (`pytest --cov-fail-under`, `go-test-coverage`), with no account or token;
  949. set it to today's coverage. Templates live in `fixer/templates.yaml` and pin
  950. every action to a commit with its release in a comment, so the generated
  951. workflow passes zizmor; images, packages and binaries are pinned to a release.
  952. Adding one is a self-contained contribution.
  953. ### Generating a workflow
  954. `--write` generates a standalone `.github/workflows/zanadir-suggested.yml`
  955. instead of printing:
  956. ```sh
  957. zanadir fix --dir . --write
  958. ```
  959. ```
  960. Wrote .github/workflows/zanadir-suggested.yml (9 categories).
  961. It runs as its own job, so it repeats checkout and adds a check to pull requests.
  962. ```
  963. The categories it could not fill are listed after that, and in a comment at
  964. the top of the file.
  965. Existing workflows are never edited, so nothing you wrote can be damaged; the
  966. worst case is a file you delete. Re-running overwrites the generated file and
  967. produces the same result, and zanadir refuses to overwrite a file at that path
  968. that it did not generate.
  969. That standalone job is the trade-off: it repeats checkout and adds its own
  970. entry to the checks list, which is noisier than adding the steps to a job you
  971. already have. Move them into your own workflow whenever you prefer.
  972. `--write` currently generates GitHub Actions only. On other platforms, run
  973. without it and paste the snippets.
  974. `--excluded-categories` works as it does for `scan`.
  975. ## `zanadir skills`
  976. Agent skills (`SKILL.md` files for Claude Code, Codex and other agents) fail
  977. quietly: a vague description never triggers, a linked script was deleted, two
  978. skills compete for the same requests. `skills` finds every `SKILL.md` in a
  979. checkout, or in a GitHub repository without cloning it, and reports them:
  980. ```sh
  981. zanadir skills --dir .
  982. zanadir skills --repo github.com/owner/name
  983. zanadir skills --home # your own skills, which agents load in every project
  984. ```
  985. ```
  986. Found 3 skills: .claude/skills/deploy, .claude/skills/review, plugins/acme/skills/db-migrate
  987. Quality
  988. ! .claude/skills/deploy/SKILL.md:3 description says what the skill does but not when to use it; add a "Use when ..." sentence [description-no-trigger]
  989. ✗ plugins/acme/skills/db-migrate/SKILL.md:41 links scripts/rollback.sh, which does not exist [missing-reference]
  990. Safety
  991. ! .claude/skills/review/scripts/setup.sh:4 downloads a script and pipes it straight into a shell [pipe-to-shell]
  992. 1 error, 2 warnings
  993. ```
  994. | Rule | Severity | Finds |
  995. |---|---|---|
  996. | `frontmatter-invalid` | error | frontmatter that is not valid YAML |
  997. | `missing-reference` | error | a link to a file in the repository that does not exist |
  998. | `hidden-unicode` | error | bidirectional overrides or tag characters, which can hide text from a reviewer; a warning for zero-width characters in `SKILL.md` |
  999. | `frontmatter-missing`, `name-missing`, `description-missing` | warning | no frontmatter, name or description |
  1000. | `name-format`, `name-mismatch` | warning | a name that is not lowercase-hyphenated, or does not match its directory |
  1001. | `description-short`, `description-long` | warning | under 40 characters, or over the 1,024 the Agent Skills specification allows |
  1002. | `description-no-trigger` | warning | a description that says what, never when ("Use when ...") |
  1003. | `description-overlap` | warning | two skills in one skills directory whose descriptions share most of their words |
  1004. | `body-long` | warning | a `SKILL.md` over 500 lines, which loads whole every time |
  1005. | `bash-unrestricted` | warning | `allowed-tools` granting every shell command |
  1006. | `pipe-to-shell`, `skip-approvals` | warning | `curl \| sh`, or running the agent without approvals or its sandbox, in `SKILL.md` or a script |
  1007. The safety rules are shallow on purpose and read only what the agent follows
  1008. or runs, not reference documents that describe a risky pattern. For a security
  1009. audit of a skill, use [SkillSpector](https://github.com/nvidia/skillspector).
  1010. `--output json` gives the findings to other tools, `--output sarif` to GitHub
  1011. code scanning, and `--output markdown` to a pull request comment; `--enforce`
  1012. exits non-zero when any error is found. The SARIF has its own code scanning
  1013. category, `zanadir/skills/`, so uploading it does not replace a scan's
  1014. results. The Markdown lists errors first, at most 50 findings, and starts with
  1015. `<!-- zanadir-skills-report -->` so a workflow can update its last comment.
  1016. `--home` checks the skills agents load for you in every project:
  1017. `~/.claude/skills` (or `$CLAUDE_CONFIG_DIR/skills`) for Claude Code,
  1018. `~/.agents/skills` and `~/.codex/skills` for Codex, and `~/.cursor/skills` for
  1019. Cursor, which reads the others too. A skill folder that is a symlink is read
  1020. where it points, as the agents do, and a skill linked from two places is
  1021. checked once. Skills inside installed plugins are not read yet. Dependency, test and `.git` directories are
  1022. skipped. `--repo` fetches only the skill directories' files, as `scan --repo`
  1023. fetches only CI files, and needs GitHub's file list to find them: a repository
  1024. too large for one listing has to be cloned and checked with `--dir`.
  1025. ## Contributors
  1026. Feedback, issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

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