From 2353671a2d9fac1810bacfe53f99bf98565960c2 Mon Sep 17 00:00:00 2001 From: dbdefault Date: Tue, 10 Nov 2026 11:01:34 +0800 Subject: [PATCH] docs: add agent setup and troubleshooting guide --- README.md | 3 ++- docs/REFERENCE.md | 3 ++- docs/agents.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 docs/agents.md diff --git a/README.md b/README.md index e1331ac..31c8ee5 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,8 @@ secfoo serve You need an agent CLI already installed and authenticated (`--agent claude|agent|agy|gemini|codex`), or an API key with the built-in -`api` agent — see [Install](#install). +`api` agent — see [Install](#install) and the +[agent setup and troubleshooting guide](docs/agents.md) for all adapters. ## Repository targets diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 4dc7f6f..fa0df8e 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -597,7 +597,8 @@ along with a `SHA256SUMS` file. - **Docker**: `ghcr.io/rakfortltd/secfoo`, built from the PyPI package on a slim Python base (simplest, most robust route for a container image — no cross-platform concern since the image itself is the platform). - **Note**: none of the 5 agent CLIs (claude, cursor, antigravity, gemini, codex) + **Note**: none of the agent CLIs listed in the + [agent setup guide](agents.md) are installed in this image, so `secfoo run` needs one made available on `PATH` inside the container yourself (e.g. a custom image built `FROM` this one, or a volume/bind mount) to actually execute a skill — without diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..25122c6 --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,52 @@ +# Agent setup and troubleshooting + +Select an adapter with `--agent`. CLI adapters must be installed on `PATH` +and authenticated before the run; secfoo cannot answer interactive prompts. +Install commands and authentication steps not specified by the adapters are +unverified here: consult the relevant agent's installation and login instructions. +The table describes the argv secfoo builds, not a command to paste verbatim. +`PROMPT` is the rendered review prompt, `WORKDIR` the target directory, and +brackets indicate optional arguments. All CLI processes run in `WORKDIR`. + +| `--agent` | Setup and command | +| --- | --- | +| `claude` | Install command unverified; subscription login is supported. `claude [--model MODEL] -p --output-format json --allowedTools TOOLS --permission-mode default --setting-sources user --strict-mcp-config --no-session-persistence [--mcp-config PATH]` (prompt on stdin). `TOOLS` starts with `Read,Grep,Glob,Bash(git log:*),Bash(git diff:*)` and includes configured MCP servers when present. The tool grant is read-only, not an OS sandbox. | +| `agent` (Cursor) | Install and authentication commands unverified. `agent [--model MODEL] -p PROMPT` | +| `agy` (Antigravity) | Install and authentication commands unverified. `agy --print PROMPT --print-timeout Ns` (`N` is the effective timeout in seconds). Headless mode denies tool calls requiring approval. | +| `gemini` | Install and authentication commands unverified. `gemini [--model MODEL] -p PROMPT --output-format json --skip-trust`. No `--yolo` write auto-approval is passed. | +| `codex` | Install and authentication commands unverified. `codex exec [--model MODEL] --sandbox read-only [-c windows.sandbox="unelevated"] --skip-git-repo-check --ephemeral --color never --cd WORKDIR -` (prompt on stdin; `-c` is Windows-only). | +| `copilot` | The adapter identifies the npm package as `@github/copilot`; install and authentication commands are unverified. `copilot [--model MODEL] --output-format json --allow-all-tools` (prompt on stdin). Tools, including writes, are auto-approved: read-only behavior relies on review instructions, not a sandbox. | +| `droid` | Install command unverified. Set `FACTORY_API_KEY` for noninteractive use. `droid exec [-m MODEL] --output-format json --cwd WORKDIR -- PROMPT`. Droid defaults to read-only; a full authenticated secfoo run was not verified in the adapter. | +| `devin` | The adapter identifies the official Homebrew cask as `devin-cli`; install command unverified. Authenticate beforehand with `devin auth login`; credential reuse for headless runs is unverified. `devin -p PROMPT --respect-workspace-trust false --permission-mode auto`. The combined command and an authenticated end-to-end run are unverified; `auto` is documented by the CLI as approving read-only tools. | +| `api` | No agent binary is invoked. If dependencies are missing, run `pip install "secfoo[api]"`. Set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GEMINI_API_KEY`. Source files are included in the API prompt. Model selection uses the configured model, then `SECFOO_API_MODEL`, then `openai/gpt-4.1-mini`. | + +`agy` and `devin` do not support adapter model selection; secfoo warns and +ignores a requested model. Other CLI model flags are shown above. + +## Troubleshooting + +- `binary_not_found`: `binary '' not found on PATH` means the CLI + was not found. Install it and make its binary available on `PATH`. + Detection checks the binary, not authentication. +- Authentication or trust prompts cannot be answered during a run: stdin + is closed or used for the prompt. Authenticate beforehand. Droid reports + `Authentication failed` without its key; Devin was observed reporting + `Error: Login canceled` without login. Gemini uses `--skip-trust`; + Devin uses `--respect-workspace-trust false` because its headless mode + cannot show the trust prompt. Check the CLI's error if trust still fails. +- `timeout`: secfoo kills the process tree. Cursor's headless mode has a + documented hang; its default timeout is 900 seconds (other CLI adapters + default to 1800). Antigravity also receives its effective print timeout. +- `failed`: inspect the error. Gemini can report `IneligibleTierError`; + the adapter suggests Antigravity (`--agent agy`) if it persists. Codex + reports a failed run if its sandbox rejects commands. Antigravity may + return empty output or `Error: Agent execution terminated due to error.`; + try another agent if it remains unreliable. Claude can put an error + reason in stdout JSON even when stderr is empty; secfoo extracts it. +- API `not_configured`: `No API key set. Set one of: OPENAI_API_KEY, + ANTHROPIC_API_KEY, GEMINI_API_KEY`. Missing LiteLLM/LangGraph dependencies + produce `failed` with the install command above. + +For a run failure, see `~/.secfoo/reports//stderr.log`; see +[Reporting bugs](../CONTRIBUTING.md#reporting-bugs) for what to include +when reporting it.