security-auditor

Overview of security-auditor skill

What security-auditor does

The security-auditor skill is a focused security review aid for code audits and vulnerability triage. It is built around OWASP Top 10 coverage, lightweight repository checks, and a simple reporting workflow rather than deep automated scanning. If you want an AI assistant to inspect application code for common security weaknesses, suggest likely findings, and structure an audit report, this skill is a practical starting point.

Who should use the security-auditor skill

Best fit readers are developers, security-minded reviewers, tech leads, and agent users who need a fast first-pass audit on an existing codebase. The security-auditor skill is especially useful when you want more structure than a generic “review this code for vulnerabilities” prompt, but do not need a full SAST platform.

Real job-to-be-done

Most users are not looking for a theory lesson on OWASP. They want to answer questions like:

• What should I check first in this repo?
• Are there obvious auth, secret, injection, or configuration risks?
• Can I get findings in a report format I can hand to a team?
• What concrete evidence should I gather before calling something a vulnerability?

This skill helps with that workflow.

What makes this skill different

The main differentiator is that security-auditor combines:

• activation rules for security-review requests
• OWASP-oriented checklists and grep-style inspection patterns
• helper scripts for secret finding and report generation
• reference files for checklist, OWASP categories, and remediation steps

That makes it more usable than a bare prompt, even though it is still lightweight and analyst-driven.

What it does not replace

This is not a substitute for:

• dependency scanners
• DAST tools
• infrastructure and cloud posture review
• manual exploit validation
• language-specific secure coding expertise for every stack

Use security-auditor for Security Audit when you need a guided review layer, not a complete security program.

How to Use security-auditor skill

security-auditor install options

If your skills workflow supports GitHub installs, the practical install path is:

npx skills add https://github.com/zhaono1/agent-playbook --skill security-auditor

If you already use the repository locally, review the skill under skills/security-auditor/.

Read these files first

For fastest adoption, read in this order:

1. SKILL.md
2. README.md
3. references/checklist.md
4. references/owasp.md
5. references/remediation.md
6. scripts/find_secrets.py
7. scripts/security_audit.py

This reading order tells you scope first, then the audit checklist, then remediation expectations, then the helper automation.

What inputs the skill needs

The security-auditor usage quality depends heavily on scope. Give it:

• repository path or target files
• app type and stack
• trust boundaries
• sensitive assets
• auth model
• deployment context
• what “done” means for this audit

A weak request is: Audit this repo for security issues.

A stronger request is: Audit the API service in ./backend for OWASP Top 10 issues. Focus on auth, IDOR, secrets exposure, SSRF, and unsafe deserialization. Assume this service handles customer billing data and uses JWT auth. Return findings with severity, file evidence, exploit path, and remediation.

How the skill activates in practice

The repository indicates the skill activates on requests involving:

• security audit
• vulnerabilities
• security review
• OWASP-related checks

In practice, be explicit. Mention the target, risk areas, and desired output format so the agent does not stay at a generic advice level.

Turn a rough goal into a better prompt

Use this pattern for better security-auditor guide results:

• Scope: which service, folder, or PR
• Risk focus: auth, secrets, injection, SSRF, crypto, logging
• Evidence standard: cite files, routes, config, or commands
• Output: table of findings with severity and fixes
• Constraints: no speculative issues without code evidence

Example:
Use security-auditor on ./src and ./config. Check for OWASP Top 10 issues, especially broken access control, hardcoded secrets, weak hashing, and unsafe external requests. For each finding, cite the exact file and code path, explain the impact, and propose the smallest safe fix.

Use the included scripts

The repository includes two practical helpers:

Run the secret scanner:

python scripts/find_secrets.py .

Generate an audit report template:

python scripts/security_audit.py --name "payments-api" --owner "platform-security"

These scripts are simple, but useful. find_secrets.py catches a few common credential patterns. security_audit.py gives you a structured report so findings are easier to hand off.

What the scripts can and cannot do

The secret scanner is intentionally lightweight. It searches text files for a small set of known patterns such as AWS-style keys, Google API keys, and sk- style tokens. It will miss many secret formats and may also flag non-production examples.

The report generator does not perform analysis. It creates a markdown audit skeleton with scope, ownership, threat model, findings, remediation, and evidence sections.

Suggested workflow for a real audit

A practical security-auditor usage flow looks like this:

1. Define audit scope and critical assets.
2. Ask the agent to inspect high-risk areas first: auth, routes, config, secrets, outbound calls.
3. Run scripts/find_secrets.py for a quick credential pass.
4. Use the checklist in references/checklist.md to avoid obvious omissions.
5. Map candidate findings to references/owasp.md categories.
6. Draft remediation using references/remediation.md.
7. Generate or fill security-audit.md with verified findings only.

This sequence keeps the audit grounded in evidence instead of generic warning lists.

High-value repo patterns to inspect first

This skill is most effective when you point it at likely security hotspots:

• route handlers and controllers
• auth middleware
• config and environment loading
• file upload logic
• URL fetchers and webhook handlers
• serialization and template rendering
• dependency manifests
• logging and monitoring code

If you ask the skill to review an entire monorepo at once, results usually get shallower.

Best use cases for security-auditor for Security Audit

Use security-auditor for Security Audit when you need:

• a first-pass security review before merge or release
• a structured audit of a small or medium codebase
• an OWASP-oriented review of API or web app logic
• evidence-backed findings for engineering follow-up
• a lightweight complement to manual review

When ordinary prompting may be enough

If you only need a one-off explanation of a single suspicious function, a normal prompt may be enough. The value of security-auditor appears when you need repeatable coverage, repository guidance, checklists, and a documented report path.

security-auditor skill FAQ

Is security-auditor good for beginners

Yes, with one caveat: beginners benefit from the checklist and OWASP framing, but they still need to verify findings. The skill helps you ask better questions and inspect common failure points, but it does not guarantee exploitability or business impact by itself.

Does the security-auditor skill scan dependencies

Not directly. The references mention dependency vulnerability scanning as part of review, but the included scripts do not perform package audit work. You should pair this skill with ecosystem-native tools such as npm audit, pip-audit, cargo audit, or equivalent scanners.

Is it only for web applications

Mostly, that is the strongest fit. The repository is centered on OWASP Top 10 categories like broken access control, injection, misconfiguration, and SSRF, which are most natural for web apps and APIs. It can still help on adjacent services, but its examples and checks are web-oriented.

How is this different from a generic security prompt

A generic prompt depends on the model to invent a method. The security-auditor skill gives the agent a clearer audit frame, explicit OWASP categories, supporting references, and scripts for common tasks. That reduces setup guesswork and makes outputs more consistent.

When should I not use security-auditor

Skip this skill if you need:

• binary analysis
• cloud IAM assessment
• container hardening review
• exploit development
• compliance-only documentation without code review
• a high-confidence automated scanner replacement

It is also a weak fit for teams expecting deep language-specific static analysis out of the box.

Does security-auditor provide remediation help

Yes, but at a light level. references/remediation.md gives a basic fix flow: reproduce, identify impact, patch, add tests, and document the change. The skill is better at structuring remediation than at providing framework-specific secure code patches for every stack.

How to Improve security-auditor skill

Give sharper scope to security-auditor

The biggest quality lever is scope definition. Tell security-auditor:

• which folders matter
• what data is sensitive
• who can access what
• which external systems are trusted
• which findings deserve priority

Without this, the skill may default to generic OWASP commentary.

Ask for evidence, not just findings

A better prompt asks for:

• exact file paths
• code snippets or line references
• attack preconditions
• realistic impact
• confidence level
• minimal remediation

This reduces false positives and makes the output usable by engineers.

Use severity and exploitability filters

Not every code smell is worth escalation. Ask the skill to separate:

• confirmed vulnerability
• likely weakness needing validation
• hardening suggestion
• non-issue after context review

That keeps your audit report from becoming a noisy list of theoretical concerns.

Pair the skill with repository-native tools

security-auditor install is only the first step. To improve output quality, combine it with:

• test suites
• dependency audit tools
• framework security linters
• secret managers and config review
• runtime logs or request traces when available

The skill becomes more valuable when it can reason over real project evidence.

Common failure modes

The main failure modes are:

• auditing too broad a scope at once
• reporting generic OWASP issues without code proof
• missing business logic context around authorization
• overtrusting the lightweight secret scanner
• treating report templates as completed analysis

Most of these are solved by tighter prompts and narrower review targets.

Iterate after the first pass

A good workflow is:

1. Ask for candidate findings.
2. Challenge each finding for evidence and exploit path.
3. Request remediation options with tradeoffs.
4. Ask for missing test cases.
5. Re-run on patched files only.

That iterative loop improves precision far more than a single broad audit prompt.

Strengthen prompts with examples of acceptable output

If you want a usable report, say so explicitly. Example:

Use security-auditor to review ./api. Return a table with Severity, OWASP Category, File, Evidence, Impact, Remediation, and Confidence. Only include findings tied to concrete code or config. Add a short "needs manual validation" section for suspicious patterns that are not yet proven.

This usually produces a better audit artifact than simply asking whether the code is secure.

Improve the skill with your own references

If you adopt this skill regularly, the easiest upgrade is to extend its references with:

• stack-specific secure coding rules
• org-approved severity definitions
• remediation examples for your framework
• internal review checklists
• known risky modules and auth patterns

That turns security-auditor from a general OWASP helper into a workflow that matches your environment.