Prompt DevOps

48 prompt
Trình Kiểm Tra Cấu Hình Dotenv và Rò Rỉ Bí Mật (Linter)
Kỹ năng
Kiểm tra (lint) các tệp .env và .env.example để phát hiện bí mật (secrets) vô tình bị commit, tên biến yếu, khóa trùng lặp, tiền tố export, khoảng trắng quanh dấu bằng, giá trị bắt buộc bị bỏ trống và nội suy không an toàn, sau đó đề xuất một tệp ví dụ đã được làm sạch. Sử dụng khi người dùng hỏi "tệp .env này có an toàn để commit không?", "tại sao dotenv không tải được?", hoặc "so sánh tệp .env.example của tôi". Bao gồm trình kiểm tra bằng thư viện chuẩn Python đã được kiểm thử.
---
name: dotenv-config-linter
description: Kiểm tra (lint) các tệp .env và .env.example để phát hiện bí mật (secrets) vô tình bị commit, tên biến yếu, khóa trùng lặp, tiền tố export, khoảng trắng quanh dấu bằng, giá trị bắt buộc bị bỏ trống và nội suy không an toàn, sau đó đề xuất một tệp ví dụ đã được làm sạch. Sử dụng khi người dùng hỏi "tệp .env này có an toàn để commit không?", "tại sao dotenv không tải được?", hoặc "so sánh tệp .env.example của tôi". Bao gồm trình kiểm tra bằng thư viện chuẩn Python đã được kiểm thử.
---

# Trình Kiểm Tra Cấu Hình Dotenv và Rò Rỉ Bí Mật (Linter)

Bạn giúp người dùng giữ cho các tệp biến môi trường luôn chính xác và an toàn. Bạn phân biệt rõ giữa các thông tin bí mật (secrets) tuyệt đối không bao giờ được commit với các giá trị giữ chỗ (placeholders) thuộc về tệp `.env.example`, phát hiện các lỗi cú pháp khiến trình nạp `dotenv` bị lỗi, và đề xuất một tệp ví dụ đã được làm sạch. Bạn không bao giờ yêu cầu người dùng dán các thông tin bí mật trên môi trường production vào khung chat nếu chỉ cần một mẫu đã che thông tin nhạy cảm là đủ.

## Các tệp trong kỹ năng này

- `scripts/dotenv_lint.py` - phân tích cú pháp dotenv, báo cáo các phát hiện ở mức HIGH/WARN/INFO, và có thể xuất ra tệp `.env.example` đã được làm sạch thông tin nhạy cảm (chỉ dùng thư viện chuẩn Python 3)
- `references/dotenv-rules.md` - các quy tắc về cú pháp và an toàn bảo mật được mã hóa trong trình kiểm tra
- `references/secret-patterns.md` - các định dạng bí mật phổ biến và cách thay thế chúng bằng giá trị giữ chỗ (placeholders)
- `templates/lint-report.md` - mẫu báo cáo kết quả trả về
- `examples/example-webapp-env-review.md` - ví dụ thực tế về việc rà soát một tệp env lộn xộn của ứng dụng web

## Quy trình làm việc

### 1. Thu thập thông tin
- Xác định tệp đó là `.env` (chứa bí mật cục bộ), `.env.example` (chứa giá trị giữ chỗ), hay cấu hình env cho CI.
- Những khóa (keys) nào là bắt buộc phải có khi khởi động hệ thống.
- Kho lưu trữ (repo) đã có công cụ quét bí mật (như gitleaks, trufflehog) hay chưa.

### 2. Chạy trình kiểm tra (linter)
```bash
python3 scripts/dotenv_lint.py .env
python3 scripts/dotenv_lint.py .env.example --example-mode
python3 scripts/dotenv_lint.py app.env --emit-example cleaned.env.example
python3 scripts/dotenv_lint.py - --json < sample.env
```
Ưu tiên sử dụng các mẫu đã che thông tin nhạy cảm. Nếu người dùng dán thông tin bí mật thật vào, hãy cảnh báo họ xoay vòng (rotate) lại bất kỳ khóa nào có nguy cơ đã bị lộ.

### 3. Khắc phục
1. Xử lý các phát hiện mức HIGH (nghi ngờ có thông tin bí mật thật trong tệp ví dụ, khóa bị trùng lặp, giá trị chứa khoảng trắng nhưng không đặt trong dấu ngoặc) trước tiên.
2. Đồng bộ tệp `.env.example` với các khóa bắt buộc bằng cách sử dụng các giá trị giữ chỗ từ `references/secret-patterns.md`.
3. Trả kết quả theo mẫu `templates/lint-report.md`.

## Quy tắc
- Không bao giờ khuyên người dùng commit tệp `.env` thật có chứa thông tin xác thực đang hoạt động.
- Không in toàn bộ giá trị bí mật trong phần tóm tắt; chỉ hiển thị ở dạng đã che (`sk-…XXXX`).
- Giữ nguyên tên các khóa trừ khi người dùng muốn đổi tên để rõ nghĩa hơn.
FILE:references/dotenv-rules.md
# Các quy tắc Dotenv mà kỹ năng này thực thi

## Cú pháp
- Mỗi dòng một cặp `KEY=VALUE`; ký tự `#` bắt đầu một dòng chú thích.
- Ưu tiên không để khoảng trắng xung quanh dấu `=`. Dạng `KEY = VALUE` sẽ bị cảnh báo mức WARN (một số trình nạp chấp nhận, nhưng nhiều trình nạp khác thì không).
- Các giá trị có chứa khoảng trắng hoặc ký tự `#` nên được đặt trong dấu ngoặc đơn hoặc ngoặc kép.
- Cú pháp `export KEY=VALUE` ở mức INFO (hoạt động trong các shell, nhưng dư thừa đối với hầu hết các trình phân tích cú pháp dotenv).
- Khóa trùng lặp: khóa xuất hiện sau cùng sẽ ghi đè các khóa trước trong nhiều trình nạp — đánh dấu ở mức HIGH vì ý đồ cấu hình không rõ ràng.

## An toàn bảo mật
- Tệp `.env.example` không được chứa các giá trị trông giống như bí mật thật đang hoạt động (chuỗi token ngẫu nhiên dài, khóa riêng tư private key, các tiền tố `sk-`/`ghp_`, các khóa có định dạng của AWS).
- Giá trị rỗng đối với các khóa được liệt kê là bắt buộc → mức WARN.
- Phép nội suy `OTHER` ở mức INFO; cần xác nhận khóa được tham chiếu có tồn tại.

## Đặt tên
- Ưu tiên định dạng `SCREAMING_SNAKE_CASE`.
- Tránh các tên chung chung như `PASSWORD` mà không có tiền tố chỉ rõ dịch vụ (nên dùng `DB_PASSWORD`).
FILE:references/secret-patterns.md
# Các mẫu bí mật → giá trị giữ chỗ (placeholders)

| Trông giống như | Giá trị giữ chỗ (Placeholder) |
|---|---|
| `sk-` + chuỗi chữ và số dài | `sk-your-openai-key` |
| `ghp_` / `github_pat_` | `ghp_your_token` |
| `AKIA` + 16 ký tự | `AKIA_YOUR_ACCESS_KEY` |
| Khối khóa riêng tư `-----BEGIN` | loại bỏ khỏi tệp ví dụ; thay vào đó hãy ghi chú đường dẫn tới tệp khóa |
| Chuỗi giống base64 dài từ 32 ký tự trở lên | `replace-me` hoặc `changeme_<purpose>` |
| URL cơ sở dữ liệu có chứa mật khẩu | `postgres://USER:PASSWORD@host:5432/db` |

Khi xuất tệp ví dụ, hãy thay thế các giá trị trông giống thông tin bí mật bằng giá trị giữ chỗ và giữ nguyên các cấu hình không nhạy cảm (cổng kết nối, cờ tính năng feature flags, URL công khai) nếu chúng rõ ràng không chứa thông tin mật.
FILE:templates/lint-report.md
# Báo cáo kiểm tra (lint) Dotenv

## Tệp đã rà soát
- Đường dẫn / vai trò: `.env` | `.env.example` | khác

## Tóm tắt
- HIGH: …
- WARN: …
- INFO: …

## Các vấn đề phát hiện
| Mức độ | Dòng | Khóa (Key) | Vấn đề | Cách khắc phục |
|---|---|---|---|---|

## Tệp `.env.example` đề xuất
```dotenv
…
```

## Cần xoay vòng (rotate) nếu bị lộ
- …
FILE:examples/example-webapp-env-review.md
# Ví dụ: tệp `.env.example` lộn xộn của ứng dụng web

**Đầu vào (chưa đạt):**
```
export DB_URL=postgres://app:SuperSecret123@db:5432/app
API_KEY = sk-proj-abcdefghijklmnopqrstuvwxyz012345
PORT=3000
PORT=3001
FEATURE_X=true
```

**Các phát hiện:**
- HIGH: `API_KEY` trông giống như một khóa kiểu OpenAI đang hoạt động nằm trong tệp ví dụ.
- HIGH: khóa `PORT` bị trùng lặp.
- WARN: có khoảng trắng xung quanh dấu `=` ở khóa `API_KEY`.
- INFO: có tiền tố `export` ở khóa `DB_URL`.
- HIGH: mật khẩu cơ sở dữ liệu được nhúng trực tiếp trong URL ví dụ.

**Tệp ví dụ sau khi làm sạch:**
```
DB_URL=postgres://USER:PASSWORD@db:5432/app
API_KEY=sk-your-openai-key
PORT=3000
FEATURE_X=true
```
FILE:scripts/dotenv_lint.py
#!/usr/bin/env python3
"""Lint .env / .env.example files for syntax and likely secrets.

Usage:
  python3 dotenv_lint.py .env
  python3 dotenv_lint.py .env.example --example-mode
  python3 dotenv_lint.py app.env --emit-example cleaned.env.example
  python3 dotenv_lint.py - --json < sample.env
"""
from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

SECRET_RES = [
    (re.compile(r"sk-[A-Za-z0-9-]{20,}"), "openai-like key"),
    (re.compile(r"ghp_[A-Za-z0-9]{20,}"), "github token"),
    (re.compile(r"github_pat_[A-Za-z0-9_]{20,}"), "github pat"),
    (re.compile(r"AKIA[0-9A-Z]{16}"), "aws access key id"),
    (re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"), "private key block"),
    (re.compile(r"(?i)password=([^&\s]{8,})"), "password in URL"),
    (re.compile(r"(?i)://[^:/@]+:[^@/]{8,}@"), "credentials embedded in URL"),
]
LINE_RE = re.compile(
    r"^(?P<export>export\s+)?(?P<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?P<val>.*)$"
)


def mask(val: str) -> str:
    if len(val) <= 8:
        return "***"
    return val[:3] + "…" + val[-4:]


def looks_placeholder(val: str) -> bool:
    v = val.strip().strip("'\"")
    low = v.lower()
    if (
        not v
        or "your-" in low
        or "changeme" in low
        or "replace" in low
        or "example" in low
        or low in {"password", "user", "todo", "xxx"}
        or "user:password@" in low
        or "://user:password@" in low
    ):
        return True
    # URL with obvious placeholders
    if "://" in v and "@" in v:
        if re.search(r"://(USER|user|USERNAME|username):(PASSWORD|password|PASS|pass|secret)@", v):
            return True
    return False


def parse_file(text: str) -> tuple[list[dict], list[dict]]:
    findings = []
    entries = []
    seen = {}
    for i, line in enumerate(text.splitlines(), 1):
        raw = line.rstrip("\n")
        stripped = raw.strip()
        if not stripped or stripped.startswith("#"):
            continue
        m = LINE_RE.match(stripped)
        if not m:
            findings.append({"severity": "HIGH", "line": i, "key": None,
                             "issue": "unparseable line", "fix": "use KEY=VALUE"})
            continue
        key, val, export = m.group("key"), m.group("val"), m.group("export")
        if re.search(r"\s=\s|=\s|\s=", raw.split("#")[0]) and " = " in raw:
            findings.append({"severity": "WARN", "line": i, "key": key,
                             "issue": "spaces around equals", "fix": f"{key}={val.strip()}"})
        if export:
            findings.append({"severity": "INFO", "line": i, "key": key,
                             "issue": "export prefix", "fix": "drop export for dotenv parsers"})
        if key in seen:
            findings.append({"severity": "HIGH", "line": i, "key": key,
                             "issue": f"duplicate key (also line {seen[key]})",
                             "fix": "keep a single definition"})
        seen[key] = i
        # strip inline comments for unquoted values
        store_val = val
        if val and not (val.startswith("'") or val.startswith('"')):
            if " #" in val:
                store_val = val.split(" #", 1)[0].rstrip()
        entries.append({"line": i, "key": key, "value": store_val, "raw": raw})
    return findings, entries


def secret_findings(entries: list[dict], example_mode: bool) -> list[dict]:
    out = []
    for e in entries:
        val = e["value"].strip().strip("'\"")
        if looks_placeholder(val):
            continue
        for rx, label in SECRET_RES:
            if rx.search(val):
                sev = "HIGH" if example_mode else "WARN"
                out.append({"severity": sev, "line": e["line"], "key": e["key"],
                            "issue": f"likely secret ({label}): {mask(val)}",
                            "fix": "replace with placeholder in example files; rotate if committed"})
                break
        else:
            # long random-ish token
            if example_mode and len(val) >= 32 and re.fullmatch(r"[A-Za-z0-9+/=_-]+", val):
                out.append({"severity": "HIGH", "line": e["line"], "key": e["key"],
                            "issue": f"long token-like value: {mask(val)}",
                            "fix": "use a placeholder like replace-me"})
    return out


def emit_example(entries: list[dict]) -> str:
    lines = []
    seen = set()
    for e in entries:
        if e["key"] in seen:
            continue
        seen.add(e["key"])
        val = e["value"].strip().strip("'\"")
        secret = False
        if not looks_placeholder(val):
            for rx, _ in SECRET_RES:
                if rx.search(val):
                    secret = True
                    break
            if len(val) >= 32 and re.fullmatch(r"[A-Za-z0-9+/=_-]+", val):
                secret = True
        if secret or (val and not looks_placeholder(val) and re.search(r"(?i)secret|password|token|api[_-]?key", e["key"])):
            if re.search(r"(?i)api[_-]?key|token", e["key"]):
                new_v = "replace-me-token"
            elif re.search(r"(?i)password|secret", e["key"]):
                new_v = "changeme"
            elif "://" in val and "@" in val:
                new_v = re.sub(r"://([^:/@]+):([^@/]+)@", r"://USER:PASSWORD@", val)
            else:
                new_v = "replace-me"
        else:
            new_v = val
        lines.append(f"{e['key']}={new_v}")
    return "\n".join(lines) + ("\n" if lines else "")


def main(argv: list[str]) -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("path", help="Env file path, or - for stdin")
    ap.add_argument("--example-mode", action="store_true",
                    help="Treat file as .env.example (secrets are HIGH)")
    ap.add_argument("--emit-example", metavar="PATH", help="Write sanitized example file")
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args(argv)

    if args.path == "-":
        text = sys.stdin.read()
    else:
        path = Path(args.path)
        if not path.is_file():
            print(f"error: file not found: {args.path}", file=sys.stderr)
            return 2
        text = path.read_text(encoding="utf-8")
    example_mode = args.example_mode or (args.path != "-" and Path(args.path).name.endswith(".example"))
    findings, entries = parse_file(text)
    findings.extend(secret_findings(entries, example_mode))
    findings.sort(key=lambda f: ({"HIGH": 0, "WARN": 1, "INFO": 2}[f["severity"]], f["line"] or 0))

    example = emit_example(entries)
    if args.emit_example:
        Path(args.emit_example).write_text(example, encoding="utf-8")

    summary = {"HIGH": 0, "WARN": 0, "INFO": 0}
    for f in findings:
        summary[f["severity"]] += 1

    if args.json:
        json.dump({"summary": summary, "findings": findings, "example": example}, sys.stdout, indent=2)
        sys.stdout.write("\n")
    else:
        print(f"summary: HIGH={summary['HIGH']} WARN={summary['WARN']} INFO={summary['INFO']}")
        for f in findings:
            key = f["key"] or "-"
            print(f"[{f['severity']}] line {f['line']}: {key}: {f['issue']} → {f['fix']}")
        if args.emit_example:
            print(f"wrote example: {args.emit_example}")
    return 1 if summary["HIGH"] else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))