diff --git a/README.md b/README.md index fa4b68da..18c38826 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,9 @@ Your code is under new management. Agents that review your code - locally or on # Initialize warden in your repository npx @sentry/warden init +# Add the built-in baseline security check +npx @sentry/warden add security-review + # Run a pre-review on current branch changes # Uses Claude Code subscription if logged in, or set WARDEN_ANTHROPIC_API_KEY npx @sentry/warden diff --git a/packages/docs/public/llms.txt b/packages/docs/public/llms.txt index 38f7f567..b276c1d6 100644 --- a/packages/docs/public/llms.txt +++ b/packages/docs/public/llms.txt @@ -4,7 +4,7 @@ Warden watches over your code by running **skills** against your changes. Skills are prompts that define what to look for: security vulnerabilities, API design issues, performance problems, or anything else you want consistent coverage on. -Skills follow the [agentskills.io](https://agentskills.io) specification. They're markdown files with a prompt that tells the AI what to look for. You can use community skills, write your own, or combine both. +Skills follow the [agentskills.io](https://agentskills.io) specification. They're markdown files with a prompt that tells the AI what to look for. Warden includes a baseline `security-review` skill by default. Treat it as a first pass, not a complete security audit, and add community or custom skills when you need deeper coverage. - Docs: https://warden.sentry.dev - GitHub: https://github.com/getsentry/warden @@ -50,7 +50,7 @@ Creates `warden.toml` (configuration) and `.github/workflows/warden.yml` (GitHub ### Add a Skill ```bash -warden add vercel-react-best-practices --remote vercel-labs/agent-skills +warden add security-review ``` ### Run Locally @@ -115,10 +115,10 @@ Add a skill trigger to your configuration. ```bash warden add # Interactive mode -warden add security-review # Add local skill +warden add security-review # Add baseline security review warden add --list # List available skills -warden add --remote getsentry/warden-skills --skill security-review -warden add --remote getsentry/warden-skills@abc123 --skill api-review # Pinned to commit +warden add --remote your-org/warden-skills --skill api-review +warden add --remote your-org/warden-skills@abc123 --skill api-review # Pinned to commit ``` ### warden sync @@ -327,7 +327,7 @@ createFixPR = true Skills can be referenced in multiple ways: ```toml -# By name (resolved from .agents/skills/ or .claude/skills/) +# By name (repo-local first, then built-in skills) [[skills]] name = "security-review" @@ -337,20 +337,21 @@ name = "./custom-skills/my-review" # Remote skill (unpinned - checks for updates every 24h) [[skills]] -name = "security-review" -remote = "getsentry/warden-skills" +name = "api-review" +remote = "your-org/warden-skills" # Remote skill (pinned to commit - cached permanently) [[skills]] -name = "security-review" -remote = "getsentry/warden-skills@abc123def" +name = "api-review" +remote = "your-org/warden-skills@abc123def" ``` Resolution order: 1. Remote repository (if `remote` field is specified) 2. Direct path (if skill contains `/`, `\`, or starts with `.`) -3. Conventional directories: `.agents/skills/`, `.claude/skills/` +3. Conventional directories: `.warden/skills/`, `.agents/skills/`, `.claude/skills/` +4. Built-in skills, including `security-review` ### Environment Variables @@ -368,6 +369,7 @@ Skills are markdown files that tell Warden what to look for. They follow the [ag ### Directory Structure ``` +.warden/skills/skill-name/SKILL.md # Warden-local generated skills .agents/skills/skill-name/SKILL.md # Primary (recommended) .claude/skills/skill-name/SKILL.md # Backup (Claude Code convention) ``` @@ -378,20 +380,19 @@ A skill has YAML frontmatter for metadata and markdown for the prompt: ```markdown --- -name: security-review -description: Review code for security vulnerabilities +name: api-review +description: Review API changes for compatibility and contract issues allowed-tools: Read Grep Glob --- -Review the code for security issues including: -- SQL injection and parameter binding -- XSS vulnerabilities in user input handling -- Hardcoded secrets or credentials -- Insecure cryptographic practices -- Path traversal vulnerabilities +Review API changes for: +- Breaking response shape changes +- Missing pagination on list endpoints +- Inconsistent error response formats +- New endpoints without authentication checks Focus on issues in the changed code. For each issue found, report: -- The specific vulnerability type +- The specific contract or compatibility risk - Why it's a problem - How to fix it ``` diff --git a/packages/docs/src/components/HeroFlow.astro b/packages/docs/src/components/HeroFlow.astro index c34f9db1..3e457087 100644 --- a/packages/docs/src/components/HeroFlow.astro +++ b/packages/docs/src/components/HeroFlow.astro @@ -1,6 +1,6 @@ --- const skills = [ - "security-scanning", + "security-review", "api-design-review", "architecture-review", "dependency-review", diff --git a/packages/docs/src/pages/cli.astro b/packages/docs/src/pages/cli.astro index fe4771b2..51ba91ca 100644 --- a/packages/docs/src/pages/cli.astro +++ b/packages/docs/src/pages/cli.astro @@ -73,12 +73,12 @@ warden init --force # Overwrite existing files`} @@ -152,7 +152,7 @@ warden setup-app --org my-org # For an organization`}
  • Remote repository (if remote is specified in trigger config)
  • Direct path (if contains /, \, or starts with .)
    • -
  • Conventional directories: .agents/skills/, .claude/skills/
    • +
  • Conventional directories: .warden/skills/, .agents/skills/, .claude/skills/
    • +
  • Built-in skills, including security-review

    • Environment Variables

    diff --git a/packages/docs/src/pages/config.astro b/packages/docs/src/pages/config.astro index 1ada9f98..f4a08c96 100644 --- a/packages/docs/src/pages/config.astro +++ b/packages/docs/src/pages/config.astro @@ -318,7 +318,7 @@ createFixPR = true`} @@ -345,7 +345,8 @@ remote = "getsentry/warden-skills@abc123def"`}
    1. Remote repository (if remote field is specified)
    2. Direct path (if skill contains /, \, or starts with .)
      3. -
    3. Conventional directories (first match wins)
      4. +
    4. Conventional directories: .warden/skills/, .agents/skills/, .claude/skills/
      5. +
    5. Built-in skills, including security-review

    Skill Files

    @@ -357,6 +358,8 @@ remote = "getsentry/warden-skills@abc123def"`}

    Warden discovers skills from these directories (first match wins):

    +
    .warden/skills/
    +
    Warden-local generated skills
    .agents/skills/
    Primary skill directory (recommended)
    .claude/skills/
    @@ -370,7 +373,7 @@ remote = "getsentry/warden-skills@abc123def"`} diff --git a/packages/docs/src/pages/guide.astro b/packages/docs/src/pages/guide.astro index 32683fa0..a9ddb68a 100644 --- a/packages/docs/src/pages/guide.astro +++ b/packages/docs/src/pages/guide.astro @@ -40,7 +40,7 @@ const tocItems = [
  • Reports findings with severity, location, and optional fixes
    • -

    Skills follow the agentskills.io specification -they're markdown files with a prompt that tells the AI what to look for. You can use community skills, write your own, or combine both.

    +

    Skills follow the agentskills.io specification -they're markdown files with a prompt that tells the AI what to look for. Warden includes a baseline security-review skill by default. Treat it as a first pass, not a complete security audit, and add community or custom skills when you need deeper coverage.

    Warden works in two contexts:

      @@ -174,7 +174,7 @@ warden src/api/`}

      Directory Structure

      -

      Create a skill in one of these directories (first match wins):

      +

      Create a custom skill in one of these directories (first match wins):

      Adding Skills -

      Warden can fetch and install skills from remote GitHub repositories.

      +

      Use built-in skills by name. Add local or remote skills when your codebase needs more specialized checks.

      + +

      Add the Baseline Security Review

      + +

      security-review ships with Warden as a baseline first pass, so no local skill file or remote repository is required:

      + + + +

      Add a Remote Skill

      @@ -273,7 +284,7 @@ Focus on issues in the changed code. For each issue found, report: diff --git a/packages/docs/src/pages/index.astro b/packages/docs/src/pages/index.astro index 4bb5a0c8..3a516343 100644 --- a/packages/docs/src/pages/index.astro +++ b/packages/docs/src/pages/index.astro @@ -8,20 +8,22 @@ import { Code } from 'astro:components'; const base = import.meta.env.BASE_URL.replace(/\/$/, ''); const skillExample = `--- -name: security-scanning +name: security-review +description: Finds exploitable application security vulnerabilities in code changes. +allowed-tools: Read Grep Glob --- -You are a security expert analyzing code changes. +You are a senior application security reviewer finding real, exploitable +vulnerabilities in code changes for Warden's baseline security skill. -## What to Report -- SQL injection via unsanitized input -- Cross-site scripting (XSS) -- Hardcoded secrets or credentials -- Command injection vulnerabilities +## Finding Requirements +- Report only when you can show attacker-controlled input, + the vulnerable sink or missing guard, the security boundary, + and concrete impact. +- Treat pattern matches as leads. A dangerous API is not a + vulnerability unless untrusted data can reach it. +- Prefer no finding over speculative hardening advice.`; -## What NOT to Report -- Code style or formatting -- Performance optimizations`; --- @@ -93,15 +95,15 @@ You are a security expert analyzing code changes.

      Its Just Skills

      -

      The PR feedback above comes from skills. Skills are a known standard: a SKILL.md file tells Warden what to look for.

      - +

      The PR feedback above comes from skills. Warden ships with a baseline security-review skill. It is a first pass, not a complete security audit, and it is still just a SKILL.md file telling Warden what to look for.

      + -

      That's a trivial example, but it's a working skill. No build step. No schema. No SDK.

      +

      Use it by name. No local skill file, build step, schema, or SDK required.

      Real skills can include detailed reference material, code examples, style guides, architectural constraints, or anything else you'd put in a design doc. The prompt is the skill.

      @@ -126,7 +128,7 @@ You are a security expert analyzing code changes. Created .github/workflows/warden.yml Next steps: - 1. Add a skill: warden add <skill-name> + 1. Add a skill: warden add security-review 2. export WARDEN_ANTHROPIC_API_KEY=sk-ant-... 3. Add WARDEN_ANTHROPIC_API_KEY to repository secrets https://github.com/your-org/your-repo/settings/secrets/actions @@ -136,9 +138,9 @@ You are a security expert analyzing code changes.

      Load Skills

      -

      Add skills for what matters to your codebase. Local or from any GitHub repo.

      - - 
      $ warden add api-design-review --remote yourcompany/skills
      +

      Start with the baseline security check. Add custom or remote skills when your codebase needs deeper coverage.

      + + 
      $ warden add security-review

      Create your own skills or find ones driven by the community at skills.sh.

      @@ -158,7 +160,7 @@ Analyzing changes from origin/main to HEAD... + src/auth/session.ts (1 chunk) ~ src/middleware/cors.ts (1 chunk) -┌─ security-scanning ────────────────────────────────────── 6.1s ─┐ +┌─ security-review ──────────────────────────────────────── 6.1s ─┐ │ 2 findings: ● 1 high ● 1 medium │ ├─────────────────────────────────────────────────────────────────┤ │ │ diff --git a/skills/warden/references/cli-reference.md b/skills/warden/references/cli-reference.md index 2192f66e..1bf0a669 100644 --- a/skills/warden/references/cli-reference.md +++ b/skills/warden/references/cli-reference.md @@ -42,7 +42,7 @@ Ambiguous targets (no path separator, no extension) are resolved by checking if | Option | Description | |--------|-------------| -| `--skill ` | Run only this skill (default: run all built-in skills) | +| `--skill ` | Run only this skill by name or path; names fall back to built-ins | | `--config ` | Path to warden.toml (default: `./warden.toml`) | | `-m, --model ` | Model to use (fallback when not set in config) | | `--json` | Output results as JSON | @@ -114,7 +114,7 @@ warden init # Interactive skill selection warden add -warden add +warden add security-review warden add --list # Remote skills diff --git a/skills/warden/references/creating-skills.md b/skills/warden/references/creating-skills.md index 3450aab6..b0ce6b82 100644 --- a/skills/warden/references/creating-skills.md +++ b/skills/warden/references/creating-skills.md @@ -7,10 +7,13 @@ Skills are markdown files that tell Warden what to look for. They follow the [ag Warden searches these directories in order (first match wins): ``` +.warden/skills/{name}/SKILL.md # Warden-local generated skills .agents/skills/{name}/SKILL.md # Primary (recommended) .claude/skills/{name}/SKILL.md # Backup (Claude Code convention) ``` +If no repo-local skill matches, names fall back to Warden's built-in skills such as `security-review`. + ## SKILL.md Format ```markdown diff --git a/src/cli/commands/init.ts b/src/cli/commands/init.ts index 3e2045df..ffe86022 100644 --- a/src/cli/commands/init.ts +++ b/src/cli/commands/init.ts @@ -71,7 +71,7 @@ function generateWardenToml(): string { # Warden reviews code using AI-powered skills triggered by GitHub events. # Built-in skills are available by name. Custom skills live in .agents/skills/ or .claude/skills/ # -# Add skills with: warden add +# Add skills with: warden add security-review version = 1 @@ -84,7 +84,7 @@ failOn = "high" reportOn = "medium" # Skills define what to analyze and when to run -# Add skills with: warden add +# Add skills with: warden add security-review # # Example skill with path filters and triggers: # @@ -402,7 +402,7 @@ export async function runInit(options: CLIOptions, reporter: Reporter): Promise< // Print next steps reporter.bold('Next steps:'); - reporter.text(` 1. Add a skill: ${chalk.cyan('warden add ')}`); + reporter.text(` 1. Add a skill: ${chalk.cyan('warden add security-review')}`); reporter.text(` 2. Set ${chalk.cyan('WARDEN_ANTHROPIC_API_KEY')} in .env.local`); reporter.text(` 3. Add ${chalk.cyan('WARDEN_ANTHROPIC_API_KEY')} to organization or repository secrets`); diff --git a/src/cli/help.ts b/src/cli/help.ts index 736b0e65..c95ad2be 100644 --- a/src/cli/help.ts +++ b/src/cli/help.ts @@ -277,7 +277,7 @@ const HELP_COMMANDS: Record = { examples: [ 'warden add', 'warden add security-review', - 'warden add --remote getsentry/skills --skill security-review', + 'warden add --remote your-org/warden-skills --skill api-review', ], }, sync: {