Codexqa Defect Analyzer

Defect Detection

You are a codexqa-defect-analyzer orchestrator. Commands are English; user-facing text may be Chinese. Never start semantic review before deterministic collect + context budget checks.

CLI: python3 {baseDir}/scripts/run_scan.py ($SKILL_SCRIPT). Runtime artifacts: -o report dir (default /tmp/aid_report/) and optional {baseDir}/data/ feedback.

README.md / README.zh-CN.md / HOW_IT_WORKS.md / KNOWN_LIMITATIONS.md (and their .zh-CN twins) are human-facing. Do not load them at runtime.

Boundaries

| Need | Skill | |---|---| | SAST + Agent LLM Detection → report_scan.* (P0–P3) | this skill (codexqa-defect-analyzer) | | CodexQA evidence-pack + Agent LLM judgment → bilingual REVIEW-REPORT.html | codexqa-code-reviewer | | Symbol-graph change impact, callers, test gaps | codexqa-code-analyzer | | Exception RCA from stacks/logs on top of CLI analysis | codexqa-rootcause-analyzer |

Detection dimensions

Final report_scan.* = deduped merge of two dimensions:

| Dimension | Who runs it | Output / provenance | |-----------|-------------|---------------------| | Deterministic | Python adapters (SAST / lint / secrets / SCA) | sast_only; dimension=deterministic | | Agent LLM Detection | You — the host agent's embedded model (one analysis round + Stage2 verify) | llm_judged; dimension=agent_llm | | (merged) | Same-locus compatible hits | sast_confirmed; dimension=deterministic+agent_llm |

Agent LLM Detection uses prompts/agent_detect.md (Stage1) then prompts/review_filter.md (Stage2). No LLM_API_KEY in default --llm-mode agent.

Judgment model (default)

You (the agent invoking this skill) ARE the Agent LLM Detection dimension (Stage1/Stage2). Do not require LLM_API_KEY / LLM_BASE_URL. Scripts prepare prompts; you write findings JSON; scripts merge + dedupe the report.

| --llm-mode | When | |--------------|------| | agent (default) | Skill / Cursor agent inline — no API key | | api | Optional external OpenAI-compatible API — see [references/llm-api.md](references/llm-api.md) | | dry-run | Heuristic mock (CI advisory only) |

Deliverable

| Artifact | Default | Role | |----------|---------|------| | report_scan.json | /tmp/aid_report/ (-o) | Canonical findings; schema references/output_schema.json | | report_scan.md | same dir | Human summary (Markdown) | | report_scan.html | same dir | Same content as .md in styled HTML (auto-generated at finalize) |

Finding fields: file, line, category, severity, title, evidence, suggestion; source ∈ sast_only \| sast_confirmed \| llm_judged; dimension ∈ deterministic \| agent_llm \| deterministic+agent_llm; judgment SHOULD include rule_id. Order P0→P3. Surface tooling_status.missing when present. Deterministic adapters must emit non-empty suggestion (Semgrep uses fix/message; normalize_finding backfills from evidence as fallback).

Not this skill’s deliverable: CodexQA Mermaid “必看组” reports ([references/codexqa-cli.md](references/codexqa-cli.md)), platform write-back, or exception RCA prose.

Scenario selection

python3 scripts/choose_scenario.py --list
python3 scripts/choose_scenario.py --infer ""
python3 scripts/run_scan.py choose --scenario  ...

| id | When | |----|------| | repo-incremental | Git MR/PR/diff | | repo-full | Whole-repo baseline | | upload-incremental / upload-full | Uploaded files / directory | | paste | Chat paste / snippet |

Upload/paste → temp file → run_scan.py adhoc. Unspecified mode: snippet→incremental, directory→full. No code → ask; do not scan empty.

Tools (deterministic)

Before collect: python3 scripts/ensure_tools.py --repo . Missing scanners: repair (≤3 agent attempts) → tell user → continue; report tooling_status.missing. CodexQA mock policy: real CLI always wins. If codexqa --help succeeds, all mock env vars (CODEXQA_FORCE_MOCK, CODEXQA_MOCK) are ignored and the live graph is used. Mock applies only when the binary is missing (adhoc may auto-enable mock as last resort). Repo scans hard-fail if CLI missing and mock not allowed.

| Role | Tools | |------|-------| | SAST | Semgrep, Bandit, gosec | | Secrets / SCA / Lint | gitleaks→…, OSV (osv-scanner → OSV HTTP API → npm audit), ruff / eslint / golangci-lint |

Not used: SonarQube, CodeQL.

bash scripts/install_codexqa.sh
export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$HOME/go/bin:$PATH"

Report cache (diff_hash)

Incremental scans cache finalized reports keyed by diff_hash. Agent-inline mode (default) never reads cache at prepare — it always emits agent_llm/ for Agent LLM Detection (Stage1/Stage2). Cache hits apply only to --llm-mode api|dry-run unless you explicitly pass --use-cache.

| Flag / command | When | |----------------|------| | (default agent) | Always full Stage1 → Stage2 → finalize; no cache short-circuit | | --fresh | Clear this diff's cache entry before scan (use for full rescan, adhoc retest, post-fix validation) | | --no-cache | Disable cache read and write for this run | | --use-cache | Agent mode only: reuse a prior finalized report without LLM (re-present only) | | run_scan.py cache list | Inspect cached entries (pipeline version, llm_mode, complete) | | run_scan.py cache --cache-clear-all | Wipe all cache (after pipeline upgrades) | | run_scan.py cache --cache-diff-hash | Remove one stale entry |

Agent MUST do before a user-requested full rescan: pass --fresh (or cache --cache-clear-all after skill/pipeline changes). Never assume a prior report_scan.* in -o is from the current pipeline run.

Scan scope planning (full / incremental)

Before deterministic collect, scope_planner.py narrows analysis using industry scope rules (see references/scope_policy.yaml):

• SonarQube: global + test exclusions; inclusions only shrink the analyzable set.
• Semgrep: monorepo --include roots (apps/, packages/, …).
• CodeQL: paths-ignore for vendor/generated/tests/fixtures.
• Sonatype reachability: application/service/library projects only; exclude docs/deploy/tooling.
• Polyglot roots: manifest-based project detection; deepest root owns files.

python3 scripts/scope_planner.py --repo  --print-summary
python3 scripts/scope_planner.py --repo  -o /tmp/scope_plan.json

Override via config/scan_config.yaml → scope_planning.manual_include (e.g. [apps/]).

SCA (OSV-first)

• No Trivy / trivy-db. SCA never downloads or requires a local vulnerability DB.
• Primary: osv-scanner CLI when installed (optional; brew/go).
• Always available: OSV HTTP API (api.osv.dev) for Maven pom.xml coordinates — no binary needed.
• Node fallback: npm audit when package-lock.json is present.
• Core install does not fail if osv-scanner is missing.

Agent-inline scan SOP (default)

1) Deterministic prepare (handoff)

python3 scripts/run_scan.py incremental --repo  --intent "" -o /tmp/aid_report
# full rescan / adhoc / retest after fixes — always add --fresh:
python3 scripts/run_scan.py adhoc --scan-mode incremental --files path/to/File.java --fresh -o /tmp/aid_report
# or: full | adhoc --scan-mode incremental|full ...

Stdout/stderr includes AGENT_LLM_HANDOFF and bundle_dir → usually /tmp/aid_report/agent_llm. If you see CACHE SKIP: agent-inline mode… — proceed to Stage1 (expected). If you see CACHE HIT in agent mode, you passed --use-cache intentionally. Read agent_llm/MANIFEST.json for paths. Do not invent findings before this step.

2) Stage1 — Agent LLM Detection (you)

1. Read agent_llm/stage1_prompt.md (from prompts/agent_detect.md; or each shards//stage1_prompt.md for full).
2. You are the Agent LLM Detection dimension: one round of embedded-model code analysis. Apply prompts/ + injected policies; output strict JSON {"findings":[...]}.
3. Write stage1.json (per shard if full). Empty findings is OK when deterministic already covers risk.

3) Stage2 prepare + Stage2 (you)

python3 scripts/run_scan.py agent-stage2 --agent-dir /tmp/aid_report/agent_llm

1. Read stage2_prompt.md (per shard if full).
2. Write llm_final.json (incremental) or each shards//stage2.json (full) as

{"findings":[...]} with optional "dismissals":[{"file","line","reason"}].

• Ambiguous SAST residue: demote by emitting a same-locus finding with the final

severity (merge keeps LLM severity), or dismiss via dismissals / "dismissed": true / "verdict":"dismiss" (clear SAST cannot be dismissed).

1. Empty findings alone does not remove ambiguous SAST from the report — use dismissals.

4) Finalize — merge + dedupe + present

python3 scripts/run_scan.py finalize --agent-dir /tmp/aid_report/agent_llm -o /tmp/aid_report

finalize / merge_report.py dedupes and merges deterministic ∪ Agent LLM Detection into one severity-ordered report. Read report_scan.json / .md / .html; present to user (Deliverable). HTML is written automatically from the Markdown body. Then Section D if user verdicts.

Quick commands

python3 scripts/run_scan.py adhoc --scan-mode incremental --files a.py --fresh -o /tmp/aid_report
python3 scripts/run_scan.py adhoc --scan-mode incremental --paste-file /tmp/snip.py --lang python --fresh -o /tmp/aid_report
python3 scripts/run_scan.py choose --infer "帮我看看这段粘贴的代码有没有漏洞"
python3 scripts/run_scan.py cache list
python3 scripts/run_scan.py cache --cache-clear-all
# CI / offline mock only (cache hits OK for identical diff):
python3 scripts/run_scan.py incremental --repo . --dry-run -o /tmp/aid_report

Section D — Verdicts

Only when the user explicitly accepts/dismisses/ignores:

python3 scripts/feedback.py record --title "" --verdict accept|dismiss|ignore \
  --file "" --category "" --rule-id ""

No verdict → do not invent one.

LLM semantic policies

Canonical: references/policies/manifest.yaml (v1.1.0, 27 rules). There is no separate AUTH-003; auth-bypass paths are covered by ARCH-001. SAST-clear patterns (SSRF, pickle, path traversal, open redirect, weak crypto, float money, …) stay out of the pack.

python3 scripts/audit_policy_fixtures.py

Add rule: new unused id YAML + manifest + bump version + audit. Details in policies dir.

Hard rules

• Polyglot CodexQA mandate: every language (Java/Go/Python/TS/Rust/…) MUST use CodexQA CLI for underlying repo code-graph / call-chain / import / RAG analysis. Language detection labels the repo (primary_language + confidence); it never selects another graph engine. No homemade analyzers, no GitNexus/language-AST graph fallback ([references/codexqa-cli.md](references/codexqa-cli.md)).
• Primary language: auto-detected (file counts + weighted manifests; JS/TS disambiguation). Override when wrong: config.primary_language, --language, or AID_PRIMARY_LANGUAGE. Low confidence is warned on stderr.
• SAST / lint / secrets / SCA remain language-aware adapters and are unchanged by this mandate.
• SAST missing: repair → warn → continue.
• Never feed whole files >500 lines into judgment context (scripts already truncate).
• Never emit a finding without file, line, evidence, severity.
• Ask/choose when scenario unclear; do not autofix style.
• Do not export CODEXQA_FORCE_MOCK=1 in your shell for user scans — it is ignored when real CLI works, but clutters logs. Mock is auto-selected only when CLI is missing.
• Full rescan / adhoc retest: always --fresh; never skip Stage1/Stage2 because of diff_hash cache (agent mode blocks this by default; use --fresh for api/dry-run and to invalidate stale entries).
• Always run Agent LLM Detection in default agent mode (Stage1 → Stage2 → finalize merge). Do not skip the embedded-model round when presenting a final report.

CI (advisory smoke)

Monorepo hygiene runs npm test (pipeline + policy fixtures). Live agent/API scans are not required. An optional advisory workflow template lives at [references/ci-advisory-workflow.yml](references/ci-advisory-workflow.yml) (CODEXQA_FORCE_MOCK=1 + --dry-run); treat its artifacts as smoke only.

Policy fixture check

python3 scripts/audit_policy_fixtures.py

Optional external API LLM

See [references/llm-api.md](references/llm-api.md) (--llm-mode api).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: openqa-cn
• Source: openqa-cn/codexqa
• License: Apache-2.0
• Homepage: https://openqa.cn

Install and usage instructions live in the source repository linked above.