Skip to content

tanviet12/vbsec / skills/vbs-scan-security

vbs-scan-security

Flagged

Use when scanning code for security vulnerabilities. Use when user says "scan security", "kiểm tra bảo mật", "security audit", "review security", or invokes `/vbs-scan-security`. Auto-delegates to sub-agents for large scans (>20 main-language files OR >30 total OR >14 days). Outputs bilingual reports (vi/en). Optional `--auto-fix` (agentic patch + verify loop) and `--sca` (live CVE lookup via OSV.dev).

FileKindSize
SKILL.mdskill md36.2 KB
VERSIONother6 B
references/chunking-strategy.mdmarkdown7.2 KB
references/data-flow-classification.mdmarkdown9.5 KB
references/dependency-scan.mdmarkdown9.7 KB
references/i18n/en.mdmarkdown8.7 KB
references/i18n/vi.mdmarkdown9.4 KB
references/language-detection.mdmarkdown7.5 KB
references/load-rules.shexecutablescript5.2 KB
references/output-format.mdmarkdown26.1 KB
references/project-context.mdmarkdown2.7 KB
references/sub-agent-prompts.mdmarkdown16.5 KB
references/validate-report.pyexecutablescript8.7 KB
rules/generic/01-hardcoded-secret.mdmarkdown5.4 KB
rules/generic/02-sql-injection.mdmarkdown5.2 KB
rules/generic/03-xss.mdmarkdown4.9 KB
rules/generic/04-idor.mdmarkdown5.7 KB
rules/generic/05-slopsquatting.mdmarkdown6.1 KB
rules/generic/06-brute-force.mdmarkdown6.9 KB
rules/generic/07-mass-assignment.mdmarkdown6.3 KB
rules/generic/08-insecure-deserialization.mdmarkdown6.3 KB
rules/generic/09-ssrf.mdmarkdown6.7 KB
rules/generic/10-path-traversal.mdmarkdown6.3 KB
rules/generic/11-csrf.mdmarkdown7.8 KB
rules/generic/12-broken-access-control.mdmarkdown7.9 KB
rules/generic/13-weak-password-hashing.mdmarkdown5.2 KB
rules/generic/14-jwt-none-algorithm.mdmarkdown5.3 KB
rules/generic/15-cors-misconfig.mdmarkdown5.3 KB
rules/generic/16-unrestricted-file-upload.mdmarkdown5.9 KB
rules/generic/17-verbose-error-debug-mode.mdmarkdown5.8 KB
rules/generic/18-missing-rate-limit.mdmarkdown10.7 KB
rules/generic/19-race-condition.mdmarkdown11.5 KB
rules/generic/20-outdated-dependency.mdmarkdown7.2 KB
rules/generic/21-command-injection.mdmarkdown6.6 KB
rules/generic/22-vulnerable-dependency.mdmarkdown5.3 KB
rules/generic/23-llm-prompt-injection.mdmarkdown9.7 KB
rules/generic/24-excessive-agency.mdmarkdown10.1 KB
rules/generic/25-tenant-isolation.mdmarkdown10.1 KB
rules/generic/26-authz-path-parity.mdmarkdown10.9 KB
rules/generic/27-excessive-data-exposure.mdmarkdown10.4 KB
rules/generic/28-business-state-integrity.mdmarkdown9.5 KB
rules/generic/29-sensitive-data-in-logs.mdmarkdown9.1 KB
rules/generic/30-auth-session-lifecycle.mdmarkdown9.4 KB
rules/generic/31-resource-exhaustion.mdmarkdown9.0 KB
rules/languages/README.mdmarkdown8.5 KB
rules/languages/dart/01-hardcoded-secret.mdmarkdown7.9 KB
rules/languages/dart/03-xss.mdmarkdown5.2 KB
rules/languages/dart/05-slopsquatting.mdmarkdown4.6 KB
rules/languages/dart/10-path-traversal.mdmarkdown6.3 KB
rules/languages/dart/12-broken-access-control.mdmarkdown8.3 KB
rules/languages/dart/17-verbose-error-debug-mode.mdmarkdown6.7 KB
rules/languages/dart/20-outdated-dependency.mdmarkdown4.7 KB
rules/languages/dart/README.mdmarkdown3.7 KB
rules/languages/dotnet/02-sql-injection.mdmarkdown5.7 KB
rules/languages/dotnet/07-mass-assignment.mdmarkdown6.0 KB
rules/languages/dotnet/08-insecure-deserialization.mdmarkdown5.7 KB
rules/languages/dotnet/17-verbose-error-debug-mode.mdmarkdown5.0 KB
rules/languages/dotnet/21-command-injection.mdmarkdown5.3 KB
rules/languages/dotnet/README.mdmarkdown1.7 KB
rules/languages/go/02-sql-injection.mdmarkdown5.2 KB
rules/languages/go/08-insecure-deserialization.mdmarkdown5.0 KB
rules/languages/go/09-ssrf.mdmarkdown5.8 KB
rules/languages/go/17-verbose-error-debug-mode.mdmarkdown6.1 KB
rules/languages/go/21-command-injection.mdmarkdown5.2 KB
rules/languages/go/README.mdmarkdown2.7 KB
rules/languages/php/02-sql-injection.mdmarkdown5.8 KB
rules/languages/php/08-insecure-deserialization.mdmarkdown6.2 KB
rules/languages/php/11-csrf.mdmarkdown6.2 KB
rules/languages/php/17-verbose-error-debug-mode.mdmarkdown6.5 KB
rules/languages/php/21-command-injection.mdmarkdown6.7 KB
rules/languages/php/README.mdmarkdown2.9 KB
rules/languages/python/02-sql-injection.mdmarkdown7.2 KB
rules/languages/python/07-mass-assignment.mdmarkdown7.3 KB
rules/languages/python/08-insecure-deserialization.mdmarkdown7.3 KB
rules/languages/python/09-ssrf.mdmarkdown7.5 KB
rules/languages/python/11-csrf.mdmarkdown7.6 KB
rules/languages/python/14-jwt-none-algorithm.mdmarkdown7.5 KB
rules/languages/python/15-cors-misconfig.mdmarkdown8.0 KB
rules/languages/python/17-verbose-error-debug-mode.mdmarkdown8.4 KB
rules/languages/python/21-command-injection.mdmarkdown8.5 KB
rules/languages/python/README.mdmarkdown3.4 KB
rules/languages/typescript/02-sql-injection.mdmarkdown7.5 KB
rules/languages/typescript/03-xss.mdmarkdown6.7 KB
rules/languages/typescript/07-mass-assignment.mdmarkdown7.4 KB
rules/languages/typescript/08-insecure-deserialization.mdmarkdown7.0 KB
rules/languages/typescript/09-ssrf.mdmarkdown7.5 KB
rules/languages/typescript/11-csrf.mdmarkdown7.3 KB
rules/languages/typescript/14-jwt-none-algorithm.mdmarkdown7.0 KB
rules/languages/typescript/15-cors-misconfig.mdmarkdown7.2 KB
rules/languages/typescript/17-verbose-error-debug-mode.mdmarkdown7.2 KB
rules/languages/typescript/21-command-injection.mdmarkdown6.7 KB
rules/languages/typescript/README.mdmarkdown3.3 KB
workflows/auto-fix.mdmarkdown18.9 KB
workflows/large-review.mdmarkdown10.5 KB
workflows/small-review.mdmarkdown10.1 KB

references/output-format.md

View on GitHub
# Output Format

Template chính thức cho báo cáo `/vbs-scan-security`. SKILL.md và workflows phải tuân thủ format này. Mọi user-facing text dùng key i18n (xem [`i18n/vi.md`](i18n/vi.md) và [`i18n/en.md`](i18n/en.md)) — KHÔNG hardcode.

## Cấu trúc tổng quan (v0.3+)

```
1. Header block (metadata)
2. Verdict line (PASS/WARN/FAIL + 1-line description)
3. Section: CRITICAL — Overview (bảng compact) → Verbose blocks per finding
4. Section: HIGH — Overview (bảng compact) → Verbose blocks per finding
5. Section: MEDIUM (bảng compact, 1 dòng per finding)
6. Section: LOW (bảng compact, 1 dòng per finding)
7. Section: PASSED CHECKS (checklist)
7b. Section: Hardening notes (tuỳ chọn, tối đa 5 dòng — KHÔNG phải finding, xem mục "Finding vs hardening note")
8. Section: Next steps (1-2 dòng)
8b. Section: Auto-fix summary (chỉ khi `--auto-fix`, xem [`../workflows/auto-fix.md`](../workflows/auto-fix.md)) — đặt sau Next steps, trước Footer
9. Footer (generated by, disclaimer, save location)
10. JSON summary (canonical EN, fenced ```json) — cho machine consumption
```

**Verbose level theo severity (v0.3+):**

| Severity | Format |
|---|---|
| CRITICAL | Bảng overview + full block (Mô tả ngắn + Tại sao nguy hiểm + Hacker khai thác + Code before/after + Đọc thêm) |
| HIGH | Bảng overview + medium block (Mô tả + Tác động + Code fix + Đọc thêm) |
| MEDIUM | Chỉ bảng compact (File:Dòng, Loại, Mô tả) |
| LOW | Chỉ bảng compact (File:Dòng, Loại, Mô tả) |

Mục đích: non-tech user đọc CRITICAL phải hiểu được tác hại + cách sửa mà không cần search Google.

---

## Template đầy đủ v0.3 (Tiếng Việt — placeholder dùng key i18n)

```markdown
# {report_title}

**{header_version}:** {vbsec_version} ({vbsec_commit})
**{header_scope}:** {scope_label}
**{header_files}:** {N} ({ext_breakdown})
**{header_primary_lang}:** {lang_code} ({using_specialized | using_generic | no_specialized})
**{header_mode}:** {mode_label}
**{header_date}:** {date}
**{header_lang}:** {lang_code}
**{header_context}:** {context_file | —}

## {verdict_label}: {verdict_value}

{verdict_description}

---

## {section_critical} ({n_critical}) — {header_overview_table}

| # | {col_file_line} | {col_rule} |
|---|---|---|
| 1 | `api/users.ts:42` | SQL-INJECTION |
| 2 | `.env:1` | HARDCODED-SECRET |
| 3 | `auth.ts:18` | WEAK-PASSWORD-HASHING |

### 🔴 [1] CRITICAL — SQL-INJECTION tại `api/users.ts:42`

**{header_short_description}:** Code ghép `req.body.id` từ user vào câu SQL không qua bảo vệ.

**{header_why_dangerous}**

Đây là lỗ hổng số 1 trong lịch sử web. Hacker chỉ cần gõ vài ký tự vào URL/form là có thể: dump toàn bộ user/password, xóa cả database, hoặc cài backdoor để chiếm server. OWASP xếp SQL injection là A03 trong Top 10 (2021). Trong 5 năm qua, các vụ rò rỉ dữ liệu lớn nhất (Equifax, LinkedIn, Yahoo) đều có liên quan đến SQL injection.

**{header_attack_scenario}**

1. Mở browser truy cập: `https://yoursite.com/users?id=1' OR '1'='1`
2. Code chạy thành câu SQL: `SELECT * FROM users WHERE id = 1' OR '1'='1`
3. Điều kiện `'1'='1'` LUÔN ĐÚNG → DB trả về **TẤT CẢ users** (kể cả admin)
4. Tiếp tục `id=1 UNION SELECT password,email FROM users` → dump toàn bộ password
5. Thời gian: 5-15 phút để có toàn bộ DB

**{header_current_code}**

\```javascript
const id = req.body.id  // {phrase_input_untrusted}
db.query(`SELECT * FROM users WHERE id = ${id}`)  // {phrase_concat_to_sink} SQL
\```

**{header_safe_code}**

\```javascript
const id = req.body.id
db.query('SELECT * FROM users WHERE id = ?', [id])  // dấu ? là placeholder, DB tự xử lý input an toàn
// hoặc với ORM (an toàn mặc định):
const user = await User.findOne({ where: { id } })
\```

**{header_read_more}:** [Rule chi tiết](skills/vbs-scan-security/rules/generic/02-sql-injection.md) · [OWASP A03 Injection](https://owasp.org/Top10/A03_2021-Injection/)

---

### 🔴 [2] CRITICAL — HARDCODED-SECRET tại `.env:1`

**{header_short_description}:** Stripe live key đã commit vào repo, ai clone hoặc xem source là thấy.

**{header_why_dangerous}**

GitHub có bot quét 24/7 tìm secret lộ. Khi bạn `git push` file `.env`, trong vài giây-vài phút bot tìm thấy key này. Với Stripe live key, kẻ tấn công có thể tạo charge giả, drain tài khoản; với AWS key, chiếm hết infrastructure và charge max billing.

**{header_attack_scenario}**

1. Repo push lên GitHub public
2. Bot (truffleHog, gitleaks, GitGuardian, hoặc bot riêng của attacker) scan commit mới trong vài giây
3. Match regex `sk_live_...` → extract key
4. Test key qua Stripe API → confirm live
5. Tạo charge to attacker's account, hoặc tạo refund tunneling
6. Thời gian từ push → exploit: **dưới 5 phút**

**{header_current_code}**

\```bash
# .env (committed to git)
STRIPE_KEY=sk_live_EXAMPLE_REPLACE_WITH_REAL_KEY_IN_PROD
\```

**{header_safe_code}**

\```bash
# 1. XOAY KEY NGAY (assume nó đã bị compromise)
# 2. Xoá .env khỏi git history:
git rm --cached .env
echo ".env" >> .gitignore
git add .gitignore
git commit -m "Untrack .env"
# 3. Force rewrite history nếu repo còn private hoặc clone mới:
# git filter-repo --path .env --invert-paths
# 4. Set key qua env var hoặc secrets manager (AWS Secrets Manager, Vault, Doppler)
\```

**{header_read_more}:** [Rule chi tiết](skills/vbs-scan-security/rules/generic/01-hardcoded-secret.md)

---

## {section_high} ({n_high}) — {header_overview_table}

| # | {col_file_line} | {col_rule} |
|---|---|---|
| 4 | `auth.ts:18` | WEAK-PASSWORD-HASHING |

### 🟠 [4] HIGH — WEAK-PASSWORD-HASHING tại `auth.ts:18`

**{header_short_description}:** Mật khẩu hash bằng MD5 — bị bẻ khóa trong vài giây bằng GPU/rainbow table.

**{header_impact}**

Nếu database bị lộ (qua SQL injection, backup leak, hoặc nội bộ làm tệ), TOÀN BỘ password user lộ trong vài giờ. User dùng cùng password ở các site khác cũng bị compromise (credential stuffing — đây là cách 80% account takeover xảy ra trong thực tế).

**{header_fix_code}**

\```javascript
// THAY:
const hash = crypto.createHash('md5').update(password).digest('hex')

// BẰNG bcrypt (chuẩn industry):
const bcrypt = require('bcrypt')
const hash = await bcrypt.hash(password, 12)  // cost factor 12 = chậm vừa đủ để hacker không brute-force được

// HOẶC argon2 (modern, OWASP recommend):
const argon2 = require('argon2')
const hash = await argon2.hash(password)
\```

**{header_read_more}:** [Rule WEAK-PASSWORD-HASHING](skills/vbs-scan-security/rules/generic/13-weak-password-hashing.md)

---

## {section_medium} ({n_medium})

| {col_file_line} | {col_rule} | {col_issue} |
|---|---|---|
| ... | ... | ... |

## {section_low} ({n_low})

| {col_file_line} | {col_rule} | {col_issue} |
|---|---|---|
| ... | ... | ... |

---

## {section_passed}

- ✓ XSS — Vue auto-escape templates, không có v-html với user data
- ✓ CORS — Origin cụ thể, không dùng wildcard
- ✓ ... (mỗi rule applicable đã check)

---

## {footer_next_steps}

{footer_next_steps_text}

---

🤖 {footer_generated_by} [vbsec]({footer_repo})

📄 **{msg_report_saved}:** `vbsec-reports/scan-2026-05-13-143022.md`

> {footer_disclaimer}

\```json
{... canonical EN JSON summary ...}
\```
```

**Ghi chú:** Khi `vbsec-reports/` không có trong `.gitignore`, thêm 1 block warning trước JSON summary:

```markdown
> ⚠️ **{msg_gitignore_warning_title}:** {msg_gitignore_warning_text}
```

---

## Template legacy (giữ làm reference cho v0.1-v0.2 — bảng compact)

```markdown
# {report_title}

**{header_version}:** {vbsec_version} ({vbsec_commit})
**{header_scope}:** {scope_label}
...

## {section_critical}

| {col_file_line} | {col_rule} | {col_issue} | {col_fix} |
|---|---|---|---|
| api/users.ts:42 | SQL-INJECTION | `db.query(\`SELECT ... ${"${req.body.id}"}\`)` | {phrase_use_parameterized} |
| .env:1 | HARDCODED-SECRET | `STRIPE_KEY=sk_live_xxxxxxxx` | {phrase_rotate_now} + {phrase_add_gitignore} |

---

## {section_high}

| {col_file_line} | {col_rule} | {col_issue} | {col_fix} |
|---|---|---|---|
| auth.ts:18 | WEAK-PASSWORD-HASHING | `crypto.createHash('md5')` | {phrase_use_bcrypt} |

---

## {section_medium}

- `routes/api.ts:55` — MISSING-RATE-LIMIT: endpoint `/api/login` không có rate limit. {phrase_validate_input}
- `package.json:14` — OUTDATED-DEPENDENCY: `lodash@4.17.4` (CVE-2019-10744). {phrase_update_dep}

---

## {section_passed}

- ✓ XSS — Vue auto-escape, không phát hiện innerHTML với user input
- ✓ CORS — Origin cụ thể, không dùng `*`
- ✓ CSRF — Token CSRF có trong form
- ✓ IDOR — Route `/api/orders/:id` có authz check
- ✓ Insecure Deserialization — Không dùng pickle/unserialize/eval
- ... (liệt kê các rule đã check và pass)

---

## {footer_next_steps}

{footer_next_steps_text}

---

🤖 {footer_generated_by} [vbsec]({footer_repo})

> {footer_disclaimer}

\`\`\`json
{
  "verdict": "FAIL",
  "summary": {
    "critical": 2,
    "high": 1,
    "medium": 2,
    "low": 0,
    "passed": 14
  },
  "scope": "uncommitted",
  "files_reviewed": 12,
  "primary_language": "typescript",
  "specialized_rules_used": false,
  "mode": "small",
  "date": "2026-05-13",
  "findings": [
    {
      "file": "api/users.ts",
      "line": 42,
      "rule_id": "SQL-INJECTION",
      "severity": "CRITICAL",
      "issue_summary": "Untrusted req.body.id in template literal SQL",
      "fix_summary": "Use parameterized query"
    },
    {
      "file": ".env",
      "line": 1,
      "rule_id": "HARDCODED-SECRET",
      "severity": "CRITICAL",
      "issue_summary": "Stripe live key committed",
      "fix_summary": "Rotate key + add .env to .gitignore"
    },
    {
      "file": "auth.ts",
      "line": 18,
      "rule_id": "WEAK-PASSWORD-HASHING",
      "severity": "HIGH",
      "issue_summary": "MD5 used for password hashing",
      "fix_summary": "Use bcrypt/argon2"
    }
  ]
}
\`\`\`
```

---

## Quy tắc render

### 1. Section nào không có finding thì bỏ section đó

Ví dụ nếu không có CRITICAL: bỏ luôn heading `## {section_critical}` và bảng tương ứng. Đừng render bảng rỗng.

### 2. Severity cap theo rule

Mỗi rule trong `rules/generic/*.md` có `severity_max` ở frontmatter. Khi flag, severity gán cho finding không được vượt `severity_max`. Có thể giảm xuống nếu context cụ thể ít nguy hiểm hơn.

Ví dụ: rule `XSS` có `severity_max: HIGH`. Nếu phát hiện XSS chỉ ở admin-only page có auth thì có thể downgrade xuống MEDIUM. Phải ghi rõ lý do downgrade vào cột Issue.

### 3. File:Line format

- Cố gắng cho ra số dòng chính xác. Nếu rule áp dụng cho cả file (vd `.env` committed): dùng `:1`.
- Nếu finding spread nhiều dòng: dùng `:start-end` (vd `routes.ts:42-58`).
- Path tương đối với git root, dùng `/` (cả trên Windows).

### 4. Issue column ngắn gọn

Tối đa 1 dòng, có thể include 1 code snippet ngắn (~60 ký tự) trong backtick. Code snippet KHÔNG bị dịch sang lang khác.

### 5. Fix column

Ưu tiên dùng phrase template từ i18n (`{phrase_use_parameterized}`, `{phrase_use_bcrypt}`...). Nếu cần custom message, viết theo lang chọn nhưng để tên technical (function name, library name) NGUYÊN tiếng Anh.

### 6. PASSED section

Liệt kê các rule mà sau khi quét **không phát hiện vấn đề**. Format:
```
- ✓ <Rule Name> — <ngắn 1 dòng giải thích đã check gì>
```

Không cần cho rule không applicable (vd: PHP rules trên repo Node — không cần liệt kê là "đã pass").

### 7. JSON summary cuối

**LUÔN dùng key tiếng Anh canonical**, bất kể `lang=vi` hay `en`. Đây là phần để CI/tooling parse. Các field:

| Field | Type | Description |
|---|---|---|
| `vbsec_version` | string | **Bắt buộc.** Nội dung file `VERSION` của skill (vd `"0.8.0"`). Cổng phát hành dựa vào field này để biết báo cáo chạy bản nào |
| `vbsec_commit` | string (optional) | Commit ngắn của skill (`git -C <skill-dir> rev-parse --short HEAD`), `"unknown"` nếu không phải git |
| `verdict` | `"PASS"\|"WARN"\|"FAIL"` | Tổng kết. Phải khớp findings (CRITICAL → FAIL, HIGH → WARN, còn lại PASS), kể cả finding `OTHER-CWE-*`. Nặng hơn chỉ khi có `verdict_downgraded_reason` |
| `summary.critical` | int | Số **findings** (không phải rule-hit) ở mức CRITICAL |
| `summary.high` | int | Số findings ở mức HIGH |
| `summary.medium` | int | Số findings ở mức MEDIUM |
| `summary.low` | int | Số findings ở mức LOW |
| `summary.passed` | int | Số rule đã check và pass (tối đa = số rule đã nạp) |
| `scope` | string | Scope label (canonical EN) |
| `files_reviewed` | int | |
| `primary_language` | string | lowercase, e.g. `"typescript"`, `"go"`, `"php"` |
| `specialized_rules_used` | bool | |
| `mode` | `"small"\|"large"` | |
| `date` | ISO 8601 date | |
| `findings[]` | array | Mỗi finding: file, line, rule_id, severity, issue_summary, fix_summary |
| `hardening_notes[]` | array (optional) | Gợi ý phòng thủ thêm, KHÔNG phải lỗ hổng: `{file, line, note}`. Không tính vào `summary` |
| `coverage` | object (optional, khuyến nghị) | `{files_read, files_grep_only, files_skipped, rules_skipped: [...], context_file}` — 3 số đếm file, rule không nạp do `load_when`, đường dẫn luật dự án hoặc null |
| `verdict_downgraded_reason` | string (optional) | LARGE mode có chunk lỗi nên verdict bị nâng nặng hơn findings |
| `top_rules_by_count[]` | array (optional) | Optional ranking; mỗi entry: `{rule_id, count}` |
| `dependencies_scanned` | object (optional) | Chỉ có khi chạy `--sca`. `{total, ecosystems: [...], vulnerable_count, scan_source: "osv.dev live"\|"static list (offline)"}` — xem [`dependency-scan.md`](dependency-scan.md) |

**Fields optional trong mỗi `findings[]` entry** (chỉ xuất hiện khi liên quan, không phải mọi finding đều có):

| Field | Khi nào có | Description |
|---|---|---|
| `cwe` | **Bắt buộc** khi `rule_id` là `OTHER-CWE-<n>`; tuỳ chọn với rule khác | `"CWE-<n>"` khớp số trong `rule_id` |
| `patch_status` | Khi chạy `--auto-fix` và finding này (CRITICAL/HIGH) đã được xử lý | `"applied"` \| `"failed_verification"` \| `"suggested_only"` \| `"skipped_low_severity"` — xem [`../workflows/auto-fix.md`](../workflows/auto-fix.md) |
| `cve_id` | Khi `rule_id: VULNERABLE-DEPENDENCY` | Alias CVE từ OSV (vd `CVE-2022-31091`), fallback OSV id nếu không có alias CVE |
| `osv_id` | Khi `rule_id: VULNERABLE-DEPENDENCY` | ID gốc từ OSV.dev (vd `GHSA-...`) |
| `package` | Khi `rule_id: VULNERABLE-DEPENDENCY` | Tên package |
| `ecosystem` | Khi `rule_id: VULNERABLE-DEPENDENCY` | `NuGet`\|`Go`\|`npm`\|`Packagist`\|`PyPI`\|`Pub` |
| `installed_version` | Khi `rule_id: VULNERABLE-DEPENDENCY` | Version hiện tại trong manifest |
| `fixed_version` | Khi `rule_id: VULNERABLE-DEPENDENCY` | Version tối thiểu đã fix theo OSV |
| `severity_source` | Khi `rule_id: VULNERABLE-DEPENDENCY` | `"osv"` \| `"ghsa_alias"` \| `"default"` — severity lấy từ đâu (xem `dependency-scan.md` Bước 3) |
| `cvss_vector` | Khi `rule_id: VULNERABLE-DEPENDENCY` và OSV có `severity[]` | String, nguyên chuỗi vector từ OSV (vd `CVSS:3.1/AV:N/AC:L/...`). Chỉ để tham khảo, không dùng để tính severity |

**Schema bắt buộc cho mỗi entry trong `findings[]` — tên key phải CHÍNH XÁC:**

| Key | Kiểu | Ràng buộc |
|---|---|---|
| `file` | string | Path tương đối từ scope root |
| `line` | int | Số nguyên >= 1 (dòng bắt đầu; không dùng `"12-27"`) |
| `rule_id` | string | Một trong các `id` ở `rules/generic/*.md`, hoặc `OTHER-CWE-<n>` cho lỗi có đường khai thác mà không rule nào khớp (kèm `cwe`, severity ≤ HIGH). KHÔNG tự đặt ID khác, KHÔNG gán rule gần nhất. Không có đường khai thác → `hardening_notes` |
| `severity` (trần) | | ≤ `severity_max` trong frontmatter của rule |
| `severity` | string | Viết hoa: `CRITICAL` \| `HIGH` \| `MEDIUM` \| `LOW` |
| `issue_summary` | string | 1 dòng |
| `fix_summary` | string | 1 dòng |

KHÔNG dùng key thay thế: `id`, `rule` (→ `rule_id`), `note`, `summary`, `issue` (→ `issue_summary`), `fix` (→ `fix_summary`). Tooling CI/CD parse theo đúng tên key trên.

**Kiểm tra trước khi kết thúc (bắt buộc):** sau khi ghi report, chạy

```bash
python3 <skill-dir>/references/validate-report.py "$REPORT_FILE"
```

Script báo lỗi → sửa JSON trong report, ghi lại, chạy lại (tối đa 2 lần). Không có `python3` → tự đối chiếu từng finding với bảng schema trên.

### Finding vs hardening note

Chỉ tạo **finding** khi có **đường khai thác cụ thể**: input attacker điều khiển được (L1/L2 theo `data-flow-classification.md`) đi tới sink nguy hiểm, hoặc cấu hình sai khai thác được ngay. Nếu chính reasoning của mình kết luận "an toàn" / "safe" / "không khai thác được" / "not reachable by current code" → **KHÔNG tạo finding**. `validate-report.py` từ chối finding có các cụm này trong `issue_summary` (trừ `OUTDATED-DEPENDENCY` / `VULNERABLE-DEPENDENCY`, nơi "CVE không reachable" chỉ là lý do hạ severity), và từ chối `issue_summary` có chữ "mapped to closest rule" / "rule gần nhất": vấn đề có đường khai thác mà không thuộc rule nào thì dùng `OTHER-CWE-<n>` (tính vào verdict), không có đường khai thác thì là hardening note; không bao giờ ép vào rule gần giống. Khi bị từ chối, chọn 1 trong 2: viết lại `issue_summary` nêu rõ attacker làm gì và lấy được gì (nếu thật sự có đường khai thác), hoặc chuyển sang hardening note. Không được chỉ xoá cụm phủ định cho qua validator.

**Ranh giới quan trọng — check viết sai vẫn là finding:** hàm kiểm tra / sanitizer / allowlist **viết sai** (`HasPrefix` thiếu dấu `/` sau `Join`, `endsWith("example.com")` không có dấu chấm, `algorithms` lấy từ header token, regex thiếu anchor, check `..` trước khi decode...) **LUÔN là finding**, kể cả khi hiện tại có yếu tố khác đang chặn khai thác (phiên bản thư viện, chưa có thư mục sibling, auth đang dùng Bearer). Lỗi nằm trong code của repo; yếu tố chặn nằm ngoài tầm kiểm soát và đổi bất cứ lúc nào. Cách ghi: giữ finding, hạ severity xuống MEDIUM nếu cần, `issue_summary` nêu điều kiện để bypass thành công ("bypass khi có thư mục `/srv/wallet/files-*`", "bypass nếu đổi sang thư viện không kiểm key type"). Không viết "not exploitable". Chỉ chuyển sang hardening note khi **input attacker không tới được sink** hoặc code không có lỗi mà chỉ thiếu một lớp phòng thủ thêm.

Ba lỗi hay gặp làm báo cáo nhiễu, đều KHÔNG phải finding:
- Tạo finding rồi tự ghi "không khai thác được" cho lỗi logic/cấu hình (khác với dependency có CVE: đó vẫn là finding, chỉ hạ severity).
- Gán `BROKEN-ACCESS-CONTROL` cho mọi endpoint không có auth trong repo chưa có cơ chế auth nào, hoặc cho endpoint đã có finding CRITICAL khác (xem rule 12 mục "Khi nào KHÔNG tạo finding").
- Gán `JWT-NONE-ALGORITHM` / `BROKEN-ACCESS-CONTROL` cho "token không hết hạn", "session không TTL" khi không chỉ ra được ai lấy được token.

Gợi ý phòng thủ thêm cho code đã an toàn (thêm header `nosniff`, cờ cookie khi không có XSS nào, bật `EMULATE_PREPARES=false`, commit lockfile, đặt timeout...) → ghi vào `hardening_notes[]` và section `{header_hardening_title}`. Không gán `rule_id`, không tính vào `summary`, không ảnh hưởng verdict.

**Quy tắc đếm findings — QUAN TRỌNG để tránh sai số:**

1. **Mỗi finding có ĐÚNG 1 `rule_id`** (primary). Không gom nhiều rule_id vào 1 finding.
2. **1 dòng code có thể tạo nhiều findings nếu trigger nhiều rule.** Ví dụ `routes/wallet.ts:12` có cả IDOR và RACE-CONDITION → tạo 2 findings riêng biệt, mỗi cái có rule_id của mình.
3. **`summary.critical/high/medium/low` = số ENTRY trong `findings[]`** lọc theo severity. Tổng `critical + high + medium + low = findings.length`.
4. **`top_rules_by_count[]` (nếu render) = group `findings[]` theo `rule_id`, count.** Tổng counts = `findings.length` (không double-count).
5. Cross-references trong `issue` cho finding khác (e.g., "see also XSS at line X") là **text note**, KHÔNG tạo finding thứ 2.

**Sanity check khi render:**
```
assert findings.length == summary.critical + summary.high + summary.medium + summary.low
assert findings.length == sum(top_rules_by_count[].count)  # nếu có render top_rules
```

Nếu sanity check fail → có dedup/count bug ở aggregate step. Re-check trước khi output.

### 8. Footer disclaimer (bắt buộc)

Mọi report đều có disclaimer `{footer_disclaimer}` — vbsec là tool tham khảo, KHÔNG thay thế audit chuyên nghiệp. Người dùng có thể tin tưởng vbsec để catch lỗi phổ biến nhưng không nên dùng làm proof bảo mật pháp lý.

---

## Ví dụ output đầy đủ — tiếng Việt

```markdown
# Báo cáo quét bảo mật vbsec

**Phạm vi:** Thay đổi chưa commit
**Số file:** 12 (8 .ts, 4 .py)
**Ngôn ngữ chính:** typescript (chưa có rule chuyên sâu)
**Chế độ:** NHỎ (quét trực tiếp)
**Ngày quét:** 2026-05-13
**Ngôn ngữ báo cáo:** vi

## KẾT LUẬN: KHÔNG ĐẠT

Có lỗi NGHIÊM TRỌNG. KHÔNG được deploy đến khi sửa hết.

---

## NGHIÊM TRỌNG (chặn deploy)

| File:Dòng | Loại lỗi | Mô tả | Cách sửa |
|---|---|---|---|
| `api/users.ts:42` | SQL-INJECTION | `db.query(\`SELECT * FROM users WHERE id = ${"${req.body.id}"}\`)` — L1 input nối thẳng | Dùng parameterized query / prepared statement |
| `.env:1` | HARDCODED-SECRET | `STRIPE_KEY=sk_live_xxxxxxxx` đã commit | Xoay key ngay (nếu đã lộ lên Git) + Thêm `.env` vào `.gitignore` |

---

## CAO (cần khắc phục)

| File:Dòng | Loại lỗi | Mô tả | Cách sửa |
|---|---|---|---|
| `auth.ts:18` | WEAK-PASSWORD-HASHING | `crypto.createHash('md5')` lưu password | Dùng bcrypt/argon2/scrypt cho mật khẩu |

---

## ĐÃ ĐẠT

- ✓ XSS — Vue auto-escape, không phát hiện innerHTML với user input
- ✓ CORS — Origin cụ thể, không dùng `*`
- ✓ CSRF — Token CSRF có trong form
- ✓ IDOR — Route `/api/orders/:id` có authz check
- ✓ Insecure Deserialization — Không dùng pickle/unserialize/eval
- ✓ Path Traversal — Không có file ops với user input
- ✓ SSRF — Server không fetch URL user-controlled
- ✓ JWT None — Không thấy JWT, không applicable
- ✓ Unrestricted File Upload — Không có upload endpoint trong scope
- ✓ Race Condition — Không thấy balance update / inventory logic
- ✓ Slopsquatting — Tất cả import packages có trong npm registry
- ✓ Mass Assignment — Endpoint dùng explicit field selection
- ✓ Command Injection — Không có exec/spawn với user input
- ✓ Verbose Error / Debug Mode — Production config tắt debug

---

## Bước tiếp theo

Sửa các lỗi NGHIÊM TRỌNG trước. Sau đó re-scan để xác nhận.

---

🤖 Báo cáo tạo bởi [vbsec](https://github.com/tanviet12/vbsec)

> Báo cáo này tham khảo — không thay thế cho audit bảo mật chuyên nghiệp.

\`\`\`json
{
  "verdict": "FAIL",
  "summary": {"critical": 2, "high": 1, "medium": 0, "low": 0, "passed": 14},
  "scope": "uncommitted",
  "files_reviewed": 12,
  "primary_language": "typescript",
  "specialized_rules_used": false,
  "mode": "small",
  "date": "2026-05-13",
  "findings": [
    {"file": "api/users.ts", "line": 42, "rule_id": "SQL-INJECTION", "severity": "CRITICAL", "issue_summary": "Untrusted req.body.id in template literal SQL", "fix_summary": "Use parameterized query"},
    {"file": ".env", "line": 1, "rule_id": "HARDCODED-SECRET", "severity": "CRITICAL", "issue_summary": "Stripe live key committed", "fix_summary": "Rotate key + add .env to .gitignore"},
    {"file": "auth.ts", "line": 18, "rule_id": "WEAK-PASSWORD-HASHING", "severity": "HIGH", "issue_summary": "MD5 used for password hashing", "fix_summary": "Use bcrypt/argon2"}
  ]
}
\`\`\`
```

---

## Ví dụ ngắn — tiếng Anh (cùng repo, cùng findings)

```markdown
# vbsec Security Scan Report

**Scope:** Uncommitted changes
**Files:** 12 (8 .ts, 4 .py)
**Primary language:** typescript (no specialized rules available)
**Mode:** SMALL (inline scan)
**Scan date:** 2026-05-13
**Report language:** en

## VERDICT: FAIL

CRITICAL issues found. DO NOT deploy until fixed.

## CRITICAL (blocks deploy)

| File:Line | Rule | Issue | Fix |
|---|---|---|---|
| `api/users.ts:42` | SQL-INJECTION | `db.query(\`SELECT * FROM users WHERE id = ${"${req.body.id}"}\`)` — L1 input concatenated | Use parameterized query / prepared statement |
| `.env:1` | HARDCODED-SECRET | `STRIPE_KEY=sk_live_xxxxxxxx` committed | Rotate the key immediately (if it was pushed to Git) + Add `.env` to `.gitignore` |

... (rest mirrors vi version with EN strings)
```

JSON block ở cuối **giống y hệt** version vi — canonical EN, không đổi.

---

## Edge cases

| Scenario | Cách render |
|---|---|
| Repo PASS hoàn toàn (no findings) | Hiện header + verdict PASS + section PASSED + footer. Không có section CRITICAL/HIGH/MEDIUM/LOW. |
| Scope rỗng (no files) | Render header với "Files: 0" + msg "{msg_no_files}". Bỏ qua tất cả section findings. Verdict = PASS (mặc định). |
| Multi-lang repo | `header_primary_lang` ghi 2 lang, e.g. `"go + vue (cả 2 đều dùng specialized)"`. |
| Rule không applicable | Không đưa vào PASSED list, không hiện. Ví dụ: PHP rules trong repo thuần Node. |
| Sub-agent (LARGE mode) finding bị conflict | Main agent dedup theo `file:line:rule_id`. Giữ severity cao nhất. |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall