--- name: cefense-setup description: Install and set up Cefense in a repository. Use when someone asks to set up Cefense, connect a repository to Cefense, install the Cefense CLI, sign in to Cefense, or scan a repository for vulnerabilities for the first time. Once setup finishes, `cf skill install` writes the full Cefense skill into this project for every coding agent it detects. license: MIT metadata: version: 2 homepage: https://cefense.com package: "@cefense-npm/cefense-cli" --- # Set up Cefense This document gets Cefense working in one repository, then hands you a better one. ## What Cefense is Cefense scans a GitHub repository, reports the vulnerabilities in its code, joins each one to the public security research that explains it, writes a patch, and opens a pull request. It runs against what has been committed and scanned, so it is a security review of the repository, not a linter on the file you are editing. It is worth reaching for when someone asks whether a repository is vulnerable, what to fix first, why a finding is real, or to patch one and open the pull request. It is the wrong tool for grading code that has not been pushed yet. ## What you are about to do 1. Install the `cf` command. 2. Sign the user in. 3. Connect the repository and scan it. 4. Run `cf skill install`, which writes the full Cefense skill into this project for whichever coding agents it finds. That document, not this one, is the guide to using Cefense day to day. Work through it in order. Each step names the failure that sends you back a step. ## The contract Pass `--agent` to every command. It prints exactly one line of JSON to stdout, never opens the interactive view, and never asks a question. ```json {"schemaVersion":1,"ok":true,"command":"status","data":{"...":"..."},"next":["cf reproduced --agent"]} {"schemaVersion":1,"ok":false,"command":"repo connect","error":{"code":"auth_required","message":"...","remedy":"...","exitCode":3}} ``` Branch on `error.code`, never on `error.message`. Exit codes: `0` fine, `2` usage, `3` not signed in, `4` API failure. ## Step 0. Check whether it is already done ```sh cf status --agent ``` `"ok":true` means the CLI is installed, the user is signed in, and `data.repositories` lists what is connected. Jump to step 5. `command not found` sends you to step 1. `"code":"auth_required"` sends you to step 2. ## Step 1. Install the CLI Node 22.12 or newer is required. Check with `node --version`. ```sh npm install -g @cefense-npm/cefense-cli cf --version ``` The package installs two identical binaries, `cf` and `cefense`. This document uses `cf`. If you cannot install globally, prefix every command below with `npx -p @cefense-npm/cefense-cli`, as in `npx -p @cefense-npm/cefense-cli cf status --agent`. The bare `npx @cefense-npm/cefense-cli` form does not work, because the package name matches neither binary. ## Step 2. Sign in Sign-in is OAuth in a browser. There is no API token to paste, so never ask anyone for a token or a password. `cf auth login` blocks until the browser round trip finishes. Do not run it in the foreground and wait on it. The clean path, when a person is there: 1. Ask them to run `cf auth login` in their own terminal. 2. Poll `cf auth status --agent` every few seconds until `data.authenticated` is true. If you have to run it yourself, background it and read the sign-in URL off **stderr**, the one case where stderr carries something you need: ```sh cf auth login --agent >/tmp/cefense-login.json 2>/tmp/cefense-login.url & ``` Give it a second, show the user the URL from `/tmp/cefense-login.url`, then poll `cf auth status --agent`. Stop after about five minutes and tell them it did not complete. In CI, where there is no browser at all, set `CEFENSE_TOKEN` in the environment instead. The CLI reads it directly and `cf auth login` is never needed. Never write that value into a file in the repository. ## Step 3. Check the GitHub connection ```sh cf auth status --agent ``` Read `data.github.connected`. If it is false, Cefense cannot see any repositories, and the CLI cannot fix that: installing the GitHub App happens in a browser. Send the user to https://cefense.com/app/repositories, wait, then check again. Do not try to work around this. ## Step 4. Connect the repository and scan it Always pass `owner/name`. With no argument the CLI opens a picker, which needs a terminal it does not have here. ```sh cf repo connect acme/api --agent ``` This connects the repository and queues its first scan, returning `{"connected":[{"repository":"acme/api","scanId":"..."}]}` straight away. A `usage_error` saying the repository is not available to Cefense on GitHub means the GitHub App was never granted access to it, which is granted in the browser on the same page as step 3. Then poll for the scan: ```sh cf status --agent ``` Find the repository in `data.repositories` and read `scan.status`: `queued`, `running`, `completed`, or `failed`. Check every ten seconds or so. A first scan of a large repository can take several minutes. ## Step 5. Install the skill ```sh cf skill install ``` This writes the full Cefense skill into the repository, in the native format of every coding agent it detects: Claude Code, Cursor, GitHub Copilot, Google Antigravity, Windsurf, Devin, Cline, Gemini CLI, and `AGENTS.md` for Codex and everything else that reads it. If it detects nothing, it writes `AGENTS.md`. ```sh cf skill list # what is supported, what is detected here cf skill install claude cursor # name them instead of detecting cf skill install --all # every supported agent cf skill install --global # for your user, not this repository cf skill uninstall # remove all of it ``` Tell the user which files were written, since they are part of the repository and belong in a commit. Then read the installed skill (`.cefense/SKILL.md`, or the file listed for your own agent) before doing anything else with Cefense. It covers the parts this document does not: filters, the fix lifecycle, how to read a finding's data flow, error codes, and the rules around opening pull requests. ## Enough to be useful right now If you need to act before reading the full skill: ```sh cf reproduced --repo acme/api --severity critical,high --agent # what was found cf reproduced show --repo acme/api --agent # one finding, in full cf fix generate --wait --agent # write a patch cf fix publish --yes --agent # open the pull request ``` `cf fix publish` opens a real pull request on the user's GitHub repository. Without `--yes` it refuses with `confirmation_required`, and that gate exists so an agent cannot open pull requests on its own initiative. Ask the user first, and show them the diff. `--yes` is not a flag to add because a command failed. ## Rules - Never run `cf fix publish` without the user agreeing to it in this conversation. - Never ask for a token or write credentials to a file. The CLI keeps its token in the operating system keychain. - Do not connect repositories the user has not asked you to connect. - If something is not in the JSON, say so instead of filling the gap. Documentation: https://cefense.com/docs. Source: https://github.com/Cefense/CLI.