pageel/para-workspace/scan-sec

scan-sec — Security Scanner for Vibe Coders (Antigravity variant)

Scan security vulnerabilities for AI-generated code (vibe code). This skill checks for the 21 most common vulnerabilities of vibe code, inheriting the SMALL/LARGE mode architecture, generalized cross-language + deep-dive for Go/PHP/Python/TypeScript/.NET.

Platform: Google Antigravity. This version uses sequential chunking to preserve portability — ~3× slower but identical output.

Resource Router

Extensible Security Engine & Domain Profiles

scan-sec automatically discovers and loads domain-specific security rules:

• Universal OWASP Baseline: Secrets, Auth/RBAC, Input Injection, Transport/TLS, Resource Limits.
• Healthcare & Medical (HIPAA): Patient Data Isolation, Audit Logs, PII/PHI Redaction.
• FinTech & E-commerce (PCI-DSS): Key Tokenization, Anti-Fraud, Transaction Protection.
• Multi-Tenant SaaS: Row-Level Security (RLS), Tenant Isolation Boundaries.
• AI & Agentic Systems: Prompt Injection Guards, Tool Execution Sandboxing.
• Custom Project Rules: Dynamic loading from Projects/<name>/.agents/rules/*security*.md.

Invocation

In the Antigravity Agent Manager chat box:

• Auto-trigger: speak naturally — "scan security for this repo", "check security", "security audit". Antigravity automatically matches the description and loads the skill.
• Explicit slash command: if the workspace contains .agents/workflows/scan-sec.md, type /scan-sec to invoke.

Output Language Selection: lang=vi / --vi (default) or lang=en / --en.

Examples:

scan security uncommitted lang=en
/scan-sec project app-tinycrm
/scan-sec plan Projects/website-hcc/artifacts/plans/v1.6.0-2026-08-13-google-sheets-notification.md
audit security resource para-workspace lang=vi

CRITICAL: How to use this skill (for LLM agent)

The bash/grep patterns in the rule files are EXAMPLES, NOT commands to be run literally.

Principles

1. Reason, do not just pattern-match — Understand the security intent behind each check, do not just search for strings.
2. Use appropriate tools — Antigravity has built-in file/grep tools (read, grep, search). Do not call raw shell grep/find when native tools are available.
3. Read complete context — When finding a pattern, read the surrounding function to understand if it is a real vulnerability.
4. Data flow trust levels — A string formatting query is only dangerous if the interpolated data is L1 (untrusted).
5. No Auto-Remediation (Strict Guardrail) — The Agent MUST NOT modify, edit, or refactor any codebase file to fix vulnerabilities during or after the scan without explicit user request. The scanner is strictly a diagnostic tool. Remediation is user-led.

Data Flow Classification (L1–L4)

Key insight: f"SELECT ... {x}" is SAFE if x is L3+. It is CRITICAL if x is L1 without parameterization.

Refer to: `references/data-flow-classification.md`.

Workflow

┌─────────────────────────────────────────────────────────────────────┐
│      scan-sec WORKFLOW (Antigravity — Sequential)                   │
├─────────────────────────────────────────────────────────────────────┤
│  [Step 0] Parse args → scope + lang                                  │
│  [Step 1] Gather files (git)                                         │
│  [Step 2] Detect primary code language                               │
│  [Step 3] Route by size:                                             │
│           SMALL (≤20 main, ≤30 total, ≤14d) → inline                 │
│           LARGE (exceeding threshold)        → sequential chunking   │
│  [Step 4] Apply 21 rules (generic + lang overlay)                    │
│  [Step 5] Generate bilingual report + save to reports/security/      │
└─────────────────────────────────────────────────────────────────────┘

Step 0: Parse Arguments

Offload CLI argument parsing and file gathering to the helper script:

# Execute arguments parser script
bash .agents/skills/scan-sec/scripts/parse-args.sh "$ARGUMENTS"

Note: Skill works on non-git folders. Default scope (all) uses find instead of git ls-files. Git-specific scopes (staged, uncommitted, commit within, commit id, pr id) require git.

Step 1: Load i18n Strings

Read i18n file corresponding to $LANG:

• lang=vi → read `references/i18n/vi.md`
• lang=en → read `references/i18n/en.md`

The i18n file contains key-value pairs for all user-facing strings. All report text must come from i18n, DO NOT hardcode.

Strings NEVER translated: rule ID, file path, code snippet, command name.

Step 2: Detect Primary Code Language

Read `references/language-detection.md`. Summary:

1. Count extensions in file list: .go, .py, .php, .js, .ts, .jsx, .tsx, .rb, .java, .rs, .cs, .csproj, .sln
2. Primary lang = language representing ≥30% of total files
3. If rules/languages/<lang>/ exists → load overlay; otherwise → use generic rules only
4. Multi-lang repo (e.g. Go backend + Vue frontend) → load both overlays

Currently supported language overlays: go, php, typescript (JS+TS combined), python, dotnet.

Step 3: Route by Size

If ANY condition goes to LARGE → use LARGE mode.

• SMALL mode: Read `workflows/small-review.md` — inline scan.
• LARGE mode: Read `workflows/large-review-sequential.md` — chunk + process sequentially.

Step 4: Apply Rules

For each rule in rules/generic/ (01-21):

1. Read rule file → understand intent, severity, search patterns.
2. Apply to files in scope.
3. For each match: trace data flow (L1-L4) to classify if it is a real vulnerability.
4. If a rule with the same id exists in rules/languages/<detected-lang>/, the specific rule overrides the generic one.

Step 4.5: Graph Blast Radius & Mitigation Analysis (if --graph)

If parse-args.sh outputs Use Graph: true, execute blast radius analysis for each finding (MEDIUM severity and above):

1. Build Graph: Run /para-graph build [project-name] (or /para-graph build @resources/[namespace] for resources) to ensure the graph database is fresh.
2. Execute Graph Analyzer: Run the analyzer script to query the call tree:

``bash node .agents/skills/scan-sec/scripts/graph-analyzer.js --project <project_path> --file <relative_file_path> ``

1. Parse Output: Extract callerCount, severityBoost, mermaid, and remediationPoints.
2. Boost Severity: If severityBoost is elevated (e.g. HIGH or CRITICAL), upgrade the finding's severity level.
3. Add to Finding Details: Keep the Mermaid call graph and remediation points in memory to embed them into the final report.

Step 5: Generate Report

Refer to template in `references/output-format.md`. Core rules:

Verbose level by severity:

• CRITICAL → overview table + full verbose block per finding
• HIGH → overview table + medium block per finding
• MEDIUM → compact table only (or full block if --graph contains blast radius)
• LOW → compact table only

OWASP Mapping & Packaged References:

• For each finding, read references/owasp/mappings.json to resolve its corresponding OWASP Top 10 category.
• Display the resolved OWASP category tag next to the rule name (e.g., HARDCODED-SECRET [OWASP A02/A05]).
• Provide local relative/absolute file:/// links to the local markdown documents packaged under references/owasp/2025/en/ so users can read the detailed official guides offline.

Graph Blast Radius & Remediation (if `--graph`):

• Display Caller Count: N next to the finding file path.
• Include a "Blast Radius (Upstream Callers)" sub-section showing the Mermaid flowchart.
• Include a "Suggested Remediation Points" list detailing where sanitization or validation controls should be placed.

Layout:

1. Header block (scope, file count, primary lang, mode, date, lang code)
2. VERDICT + 1-line description
3. CRITICAL section
4. HIGH section
5. MEDIUM section
6. LOW section
7. PASSED CHECKS
8. Next steps
9. Save notification
10. Gitignore warning (if needed)
11. Footer + disclaimer
12. JSON summary (canonical EN)

Save-to-file: write the ENTIRE report (identical to stdout) to the Report file path printed by the parse-args.sh script (e.g., reports/security/scan-<timestamp>.md or artifacts/reports/security/scan-<timestamp>.md) using Antigravity write tool.

Then print 1-2 summary lines to stdout:

📄 {msg_report_saved}: <Report file path>
⚠️ {msg_gitignore_warning_title}: {msg_gitignore_warning_text}

All headers, labels, and verdicts must come from the i18n file loaded in Step 1.

Next Steps & Actionable Workflows:

• If the scan fails (Verdict: FAIL or WARN due to findings), the Agent MUST actively suggest that the user initiate a follow-up workflow:
• /brainstorm: To discuss design trade-offs and structural changes.
• /plan create: To design a security mitigation plan.
• /vibecode: To fix and verify vulnerabilities in sandbox mode.

Verdict Logic

WARN is not an approval. The report should specify HIGH issues to be fixed before production.

Differences with Claude Code variant