Prompt Infrastructure

---
name: skill-master
description: Phát hiện các mẫu kiến trúc trong mã nguồn và tự động tạo các tệp SKILL cho .claude/skills/. Sử dụng khi phân tích dự án để tìm các kỹ năng còn thiếu, tạo kỹ năng mới từ các mẫu mã nguồn hoặc đồng bộ hóa kỹ năng với cấu trúc dự án.
version: 1.0.0
---

# Skill Master

## Tổng quan

Phân tích mã nguồn (codebase) để phát hiện các mẫu kiến trúc (patterns) và tạo mới/cập nhật các tệp SKILL trong `.claude/skills/`. Hỗ trợ các dự án đa nền tảng với khả năng nhận diện mẫu đặc thù theo từng ngăn xếp công nghệ (stack-specific).

**Khả năng:**
- Quét mã nguồn để tìm các mẫu kiến trúc (ViewModel, Repository, Room, v.v.)
- So sánh các mẫu phát hiện được với các kỹ năng hiện có
- Tự động tạo các tệp SKILL kèm ví dụ mã nguồn thực tế
- Theo dõi phiên bản và cập nhật thông minh

## Cách AI phát hiện và sử dụng kỹ năng này

Kỹ năng này được kích hoạt khi người dùng:
- Yêu cầu phân tích dự án để tìm các kỹ năng còn thiếu
- Yêu cầu tạo kỹ năng từ các mẫu trong mã nguồn
- Muốn đồng bộ hóa hoặc cập nhật các kỹ năng hiện có
- Đề cập đến "skill discovery", "generate skills", hoặc "skill-sync"

**Tín hiệu nhận diện:**
- Sự hiện diện của thư mục `.claude/skills/`
- Cấu trúc dự án khớp với các mẫu đã biết
- Các tệp biên dịch/cấu hình chỉ rõ nền tảng công nghệ (xem phần tài liệu tham khảo)

## Các Chế độ Hoạt động (Modes)

### Chế độ Khám phá (Discover Mode)

Phân tích mã nguồn và báo cáo các kỹ năng còn thiếu.

**Các bước:**
1. Nhận diện nền tảng thông qua các tệp biên dịch/cấu hình (xem tài liệu tham khảo)
2. Quét các thư mục mã nguồn gốc để tìm các dấu hiệu nhận biết mẫu (pattern indicators)
3. So sánh các mẫu phát hiện được với thư mục `.claude/skills/` hiện có
4. Xuất báo cáo phân tích khoảng trống thiếu hụt (gap analysis report)

**Định dạng đầu ra:**
```
Các Mẫu Phát hiện được (Detected Patterns): {count}
| Mẫu (Pattern) | Số Tệp Tìm thấy | Vị trí Ví dụ |
|---------|-------------|------------------|
| {name}  | {count}     | {path}           |

Kỹ năng Hiện có (Existing Skills): {count}
Kỹ năng Còn thiếu (Missing Skills): {count}
- {skill-name}: {pattern}, tìm thấy {file-count} tệp
```

### Chế độ Tạo mới (Generate Mode)

Tạo các tệp SKILL từ những mẫu đã phát hiện.

**Các bước:**
1. Chạy bước khám phá để xác định các kỹ năng còn thiếu
2. Đối với mỗi kỹ năng còn thiếu:
   - Tìm 2-3 tệp mã nguồn đại diện
   - Trích xuất: các câu lệnh import, chú thích (annotations), cấu trúc lớp, quy ước đặt tên
   - Trích xuất các quy tắc từ `.ruler/*.md` nếu có
3. Tạo tệp SKILL.md sử dụng cấu trúc khuôn mẫu (template)
4. Thêm thông tin phiên bản và dấu đánh dấu nguồn (source marker)

**Cấu trúc SKILL được tạo:**
```yaml
---
name: {pattern-name}
description: {Generated description with trigger keywords}
version: 1.0.0
---

# {Title}

## Overview
{Brief description from pattern analysis}

## File Structure
{Extracted from codebase}

## Implementation Pattern
{Real code examples - anonymized}

## Rules
### Do
{From .ruler/*.md + codebase conventions}

### Don't
{Anti-patterns found}

## File Location
{Actual paths from codebase}
```

## Chiến lược Tạo mới (Create Strategy)

Khi tệp SKILL mục tiêu chưa tồn tại:
1. Tạo tệp mới bằng khuôn mẫu (template)
2. Đặt `version: 1.0.0` trong phần frontmatter
3. Đưa vào đầy đủ tất cả các phần bắt buộc
4. Thêm dấu đánh dấu nguồn ở cuối tệp (xem Định dạng Dấu đánh dấu)

## Chiến lược Cập nhật (Update Strategy)

**Kiểm tra dấu đánh dấu (Marker check):** Tìm dòng `<!-- Generated by skill-master command` ở cuối tệp.

**Nếu có dấu đánh dấu (lần chạy tiếp theo):**
- Hợp nhất thông minh (Smart merge): giữ nguyên nội dung tùy chỉnh của người dùng, bổ sung các phần còn thiếu
- Tăng số phiên bản: major (thay đổi lớn không tương thích) / minor (thêm tính năng) / patch (sửa lỗi nhỏ)
- Cập nhật danh sách tệp nguồn trong dấu đánh dấu

**Nếu không có dấu đánh dấu (lần chạy đầu tiên trên tệp đã tồn tại):**
- Sao lưu: `SKILL.md` → `SKILL.md.bak`
- Sử dụng bản sao lưu làm nguồn, trích xuất nội dung liên quan
- Tạo tệp mới hoàn chỉnh kèm theo dấu đánh dấu
- Đặt `version: 1.0.0`

## Định dạng Dấu đánh dấu (Marker Format)

Đặt ở CUỐI tệp SKILL.md được tạo ra:

```html
<!-- Generated by skill-master command
Version: {version}
Sources:
- path/to/source1.kt
- path/to/source2.md
- .ruler/rule-file.md
Last updated: {YYYY-MM-DD}
-->
```

## Tài liệu Tham khảo theo Nền tảng (Platform References)

Đọc tài liệu tham khảo tương ứng khi phát hiện nền tảng:

| Nền tảng | Tệp Nhận diện | Tài liệu Tham khảo |
|----------|-----------------|-----------|
| Android/Gradle | `build.gradle`, `settings.gradle` | `references/android.md` |
| iOS/Xcode | `*.xcodeproj`, `Package.swift` | `references/ios.md` |
| React (web) | `package.json` + react | `references/react-web.md` |
| React Native | `package.json` + react-native | `references/react-native.md` |
| Flutter/Dart | `pubspec.yaml` | `references/flutter.md` |
| Node.js | `package.json` | `references/node.md` |
| Python | `pyproject.toml`, `requirements.txt` | `references/python.md` |
| Java/JVM | `pom.xml`, `build.gradle` | `references/java.md` |
| .NET/C# | `*.csproj`, `*.sln` | `references/dotnet.md` |
| Go | `go.mod` | `references/go.md` |
| Rust | `Cargo.toml` | `references/rust.md` |
| PHP | `composer.json` | `references/php.md` |
| Ruby | `Gemfile` | `references/ruby.md` |
| Elixir | `mix.exs` | `references/elixir.md` |
| C/C++ | `CMakeLists.txt`, `Makefile` | `references/cpp.md` |
| Không xác định (Unknown) | - | `references/generic.md` |

Nếu phát hiện nhiều nền tảng cùng lúc, hãy đọc nhiều tài liệu tham khảo tương ứng.

## Quy tắc

### Nên làm (Do)
- Chỉ trích xuất các mẫu đã được xác minh thực tế trong mã nguồn
- Sử dụng các ví dụ mã nguồn thực tế (ẩn danh hóa logic nghiệp vụ)
- Đưa các từ khóa kích hoạt (trigger keywords) vào phần mô tả (description)
- Giữ cho tệp SKILL.md dưới 500 dòng
- Tham chiếu đến các tệp bên ngoài cho phần nội dung chi tiết
- Bảo toàn các phần tùy chỉnh riêng trong quá trình cập nhật
- Luôn tạo bản sao lưu trước khi sửa đổi lần đầu tiên

### Không nên làm (Don't)
- Đưa vào các thông tin bí mật (secrets), token hoặc thông tin xác thực (credentials)
- Đưa vào các chi tiết logic đặc thù của nghiệp vụ kinh doanh
- Tạo các placeholder giữ chỗ mà không có nội dung thực tế
- Ghi đè lên các tùy chỉnh của người dùng mà không sao lưu
- Tạo chuỗi tham chiếu quá sâu (tối đa 1 cấp)
- Ghi tệp ra bên ngoài thư mục `.claude/skills/`

## Quy tắc Trích xuất Nội dung

**Từ mã nguồn (codebase):**
- Trích xuất: cấu trúc lớp (class structures), chú thích (annotations), mẫu import, vị trí tệp, quy ước đặt tên
- Không bao giờ trích xuất: các giá trị gán cứng (hardcoded values), bí mật (secrets), khóa API (API keys), thông tin định danh cá nhân (PII)

**Từ .ruler/*.md (nếu có):**
- Trích xuất: các quy tắc Nên làm/Không nên làm (Do/Don't), các ràng buộc kiến trúc, quy tắc phụ thuộc (dependency rules)

## Báo cáo Đầu ra (Output Report)

Sau khi tạo xong, hãy in ra:
```
SKILL GENERATION REPORT

Skills Generated: {count}

{skill-name} [CREATED | UPDATED | BACKED_UP+CREATED]
├── Analyzed: {file-count} source files
├── Sources: {list of source files}
├── Rules from: {.ruler files if any}
└── Output: .claude/skills/{skill-name}/SKILL.md ({line-count} lines)

Validation:
✓ YAML frontmatter valid
✓ Description includes trigger keywords
✓ Content under 500 lines
✓ Has required sections
```

## Ràng buộc An toàn (Safety Constraints)

- Không bao giờ ghi tệp ra bên ngoài `.claude/skills/`
- Không bao giờ xóa nội dung mà không có bản sao lưu
- Luôn sao lưu trước khi sửa đổi lần đầu tiên
- Bảo toàn các tùy chỉnh của người dùng
- Mang tính tất định (Deterministic): cùng đầu vào → cùng đầu ra
FILE:references/android.md
# Android (Gradle/Kotlin)

## Tín hiệu nhận diện
- `settings.gradle` hoặc `settings.gradle.kts`
- `build.gradle` hoặc `build.gradle.kts`
- `gradle.properties`, `gradle/libs.versions.toml`
- `gradlew`, `gradle/wrapper/gradle-wrapper.properties`
- `app/src/main/AndroidManifest.xml`

## Tín hiệu đa mô-đun (Multi-module signals)
- Có nhiều lệnh `include(...)` trong `settings.gradle*`
- Có nhiều thư mục chứa `build.gradle*` + `src/`
- Các thư mục gốc phổ biến: `feature/`, `core/`, `library/`, `domain/`, `data/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `settings.gradle*` (danh sách mô-đun)
- `build.gradle*` (thư mục gốc + các mô-đun)
- `gradle/libs.versions.toml` (các thư viện phụ thuộc - dependencies)
- `config/detekt/detekt.yml` (nếu có)
- `**/AndroidManifest.xml`

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `*/src/main/java/`, `*/src/main/kotlin/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`features/`, `core/`, `common/`, `data/`, `domain/`, `presentation/`, `ui/`, `di/`, `navigation/`, `network/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| ViewModel | `@HiltViewModel`, `ViewModel()`, `MVI<` | viewmodel-mvi |
| Repository | `*Repository`, `*RepositoryImpl` | data-repository |
| UseCase | `operator fun invoke`, `*UseCase` | domain-usecase |
| Room Entity | `@Entity`, `@PrimaryKey`, `@ColumnInfo` | room-entity |
| Room DAO | `@Dao`, `@Query`, `@Insert`, `@Update` | room-dao |
| Migration | `Migration(`, `@Database(version=` | room-migration |
| Type Converter | `@TypeConverter`, `@TypeConverters` | type-converter |
| DTO | `@SerializedName`, `*Request`, `*Response` | network-dto |
| Compose Screen | `@Composable`, `NavGraphBuilder.` | compose-screen |
| Bottom Sheet | `ModalBottomSheet`, `*BottomSheet(` | bottomsheet-screen |
| Navigation | `@Route`, `NavGraphBuilder.`, `composable(` | navigation-route |
| Hilt Module | `@Module`, `@Provides`, `@Binds`, `@InstallIn` | hilt-module |
| Worker | `@HiltWorker`, `CoroutineWorker`, `WorkManager` | worker-task |
| DataStore | `DataStore<Preferences>`, `preferencesDataStore` | datastore-preference |
| Retrofit API | `@GET`, `@POST`, `@PUT`, `@DELETE` | retrofit-api |
| Mapper | `*.toModel()`, `*.toEntity()`, `*.toDto()` | data-mapper |
| Interceptor | `Interceptor`, `intercept()` | network-interceptor |
| Paging | `PagingSource`, `Pager(`, `PagingData` | paging-source |
| Broadcast Receiver | `BroadcastReceiver`, `onReceive(` | broadcast-receiver |
| Android Service | `: Service()`, `ForegroundService` | android-service |
| Notification | `NotificationCompat`, `NotificationChannel` | notification-builder |
| Analytics | `FirebaseAnalytics`, `logEvent` | analytics-event |
| Feature Flag | `RemoteConfig`, `FeatureFlag` | feature-flag |
| App Widget | `AppWidgetProvider`, `GlanceAppWidget` | app-widget |
| Unit Test | `@Test`, `MockK`, `mockk(`, `every {` | unit-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Danh mục tính năng (Features inventory)**: các thư mục dưới `feature/`
- **Các mô-đun cốt lõi (Core modules)**: các thư mục dưới `core/`, `library/`
- **Đồ thị điều hướng (Navigation graphs)**: `*Graph.kt`, `*Navigator*.kt`
- **Các mô-đun Hilt (Hilt modules)**: các lớp `@Module`, nội dung trong `di/`
- **Các API Retrofit (Retrofit APIs)**: các interface `*Api.kt`
- **Cơ sở dữ liệu Room (Room databases)**: các lớp `@Database`
- **Các tiến trình nền (Workers)**: các lớp `@HiltWorker`
- **Proguard**: `proguard-rules.pro` nếu có

## Nguồn trích xuất lệnh (Command sources)
- Tài liệu README/docs có gọi lệnh `./gradlew`
- Các luồng công việc CI (CI workflows) có chứa các lệnh Gradle
- Các lệnh phổ biến: `./gradlew assemble`, `./gradlew test`, `./gradlew lint`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `app/src/main/`, `app/src/main/res/`
- `app/src/main/java/`, `app/src/main/kotlin/`
- `app/src/test/`, `app/src/androidTest/`
- `library/database/migration/` (các bản di trú dữ liệu Room - Room migrations)
FILE:README.md

FILE:references/cpp.md
# C/C++

## Tín hiệu nhận diện
- `CMakeLists.txt`
- `Makefile`, `makefile`
- `*.cpp`, `*.c`, `*.h`, `*.hpp`
- `conanfile.txt`, `conanfile.py` (Conan)
- `vcpkg.json` (vcpkg)

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều tệp `CMakeLists.txt` có sử dụng `add_subdirectory`
- Nhiều tệp `Makefile` trong các thư mục con
- Các thư mục `lib/`, `src/`, `modules/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `CMakeLists.txt` (các thư viện phụ thuộc, mục tiêu biên dịch - targets)
- `conanfile.*` (các thư viện phụ thuộc)
- `vcpkg.json` (các thư viện phụ thuộc)
- `Makefile` (các mục tiêu biên dịch - build targets)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `lib/`, `include/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`core/`, `utils/`, `network/`, `storage/`, `ui/`, `tests/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Class | `class *`, `public:`, `private:` | cpp-class |
| Header | `*.h`, `*.hpp`, `#pragma once` | header-file |
| Template | `template<`, `typename T` | cpp-template |
| Smart Pointer | `std::unique_ptr`, `std::shared_ptr` | smart-pointer |
| RAII | mẫu hàm hủy (destructor pattern), `~*()` | raii-pattern |
| Singleton | `static *& instance()` | singleton |
| Factory | `create*()`, `make*()` | factory-pattern |
| Observer | `subscribe`, `notify`, mẫu hàm gọi lại (callback pattern) | observer-pattern |
| Thread | `std::thread`, `std::async`, `pthread` | threading |
| Mutex | `std::mutex`, `std::lock_guard` | synchronization |
| Network | `socket`, `asio::`, `boost::asio` | network-cpp |
| Serialization | `nlohmann::json`, `protobuf` | serialization |
| Unit Test | `TEST(`, `TEST_F(`, `gtest` | gtest |
| Catch2 Test | `TEST_CASE(`, `REQUIRE(` | catch2-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Các mô-đun cốt lõi (Core modules)**: chức năng chính
- **Thư viện (Libraries)**: các thư viện nội bộ
- **Tệp tiêu đề (Headers)**: API công khai
- **Kiểm thử (Tests)**: cách tổ chức kiểm thử
- **Mục tiêu biên dịch (Build targets)**: các tệp thực thi (executables), thư viện

## Nguồn trích xuất lệnh (Command sources)
- Các mục tiêu tùy chỉnh (custom targets) trong `CMakeLists.txt`
- Các mục tiêu trong `Makefile`
- README/docs, CI
- Các lệnh phổ biến: `cmake`, `make`, `ctest`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/`, `include/`
- `lib/`, `libs/`
- `tests/`, `test/`
- `build/` (biên dịch tách rời mã nguồn - out-of-source)
FILE:references/dotnet.md
# .NET (C#/F#)

## Tín hiệu nhận diện
- `*.csproj`, `*.fsproj`
- `*.sln`
- `global.json`
- `appsettings.json`
- `Program.cs`, `Startup.cs`

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều tệp `*.csproj`
- Solution chứa nhiều dự án (projects)
- Các thư mục `src/`, `tests/` có chứa các dự án bên trong

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `*.csproj` (các gói phụ thuộc, SDK)
- `*.sln` (cấu trúc dự án)
- `appsettings.json` (cấu hình)
- `global.json` (phiên bản SDK)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `*/` (theo từng dự án)

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`Controllers/`, `Services/`, `Repositories/`, `Models/`, `Entities/`, `DTOs/`, `Middleware/`, `Extensions/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Controller | `[ApiController]`, `ControllerBase`, `[HttpGet]` | aspnet-controller |
| Service | `I*Service`, `class *Service` | dotnet-service |
| Repository | `I*Repository`, `class *Repository` | dotnet-repository |
| Entity | `class *Entity`, `[Table]`, `[Key]` | ef-entity |
| DTO | `class *Dto`, `class *Request`, `class *Response` | dto-pattern |
| DbContext | `: DbContext`, `DbSet<` | ef-dbcontext |
| Middleware | `IMiddleware`, `RequestDelegate` | aspnet-middleware |
| Background Service | `BackgroundService`, `IHostedService` | background-service |
| MediatR Handler | `IRequestHandler<`, `INotificationHandler<` | mediatr-handler |
| SignalR Hub | `: Hub`, `[HubName]` | signalr-hub |
| Minimal API | `app.MapGet(`, `app.MapPost(` | minimal-api |
| gRPC Service | `*.proto`, `: *Base` | grpc-service |
| EF Migration | `Migrations/`, `AddMigration` | ef-migration |
| Unit Test | `[Fact]`, `[Theory]`, `xUnit` | xunit-test |
| Integration Test | `WebApplicationFactory`, `IClassFixture` | integration-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối API (API endpoints)
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu (EF Core)
- **Entities/DTOs**: các mô hình dữ liệu (data models)
- **Middleware**: đường ống xử lý yêu cầu (request pipeline)
- **Background services**: các dịch vụ chạy nền (hosted services)

## Nguồn trích xuất lệnh (Command sources)
- Các mục tiêu trong `*.csproj`
- README/docs, CI
- Các lệnh phổ biến: `dotnet build`, `dotnet test`, `dotnet run`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/*/`, các thư mục dự án
- `tests/`
- `Migrations/`
- `Properties/`
FILE:references/elixir.md
# Elixir/Erlang

## Tín hiệu nhận diện
- `mix.exs`
- `mix.lock`
- `config/config.exs`
- Các thư mục `lib/`, `test/`

## Tín hiệu đa mô-đun (Multi-module signals)
- Ứng dụng dạng Umbrella (thư mục `apps/`)
- Nhiều tệp `mix.exs` trong các thư mục con
- Thư mục `rel/` dành cho các bản phát hành (releases)

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `mix.exs` (các thư viện phụ thuộc, cấu hình)
- `config/*.exs` (cấu hình)
- `rel/config.exs` (bản phát hành)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `lib/`, `apps/*/lib/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`controllers/`, `views/`, `channels/`, `contexts/`, `schemas/`, `workers/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Phoenix Controller | `use *Web, :controller`, `def index` | phoenix-controller |
| Phoenix LiveView | `use *Web, :live_view`, `mount/3` | phoenix-liveview |
| Phoenix Channel | `use *Web, :channel`, `join/3` | phoenix-channel |
| Ecto Schema | `use Ecto.Schema`, `schema "` | ecto-schema |
| Ecto Migration | `use Ecto.Migration`, `create table` | ecto-migration |
| Ecto Changeset | `cast/4`, `validate_required` | ecto-changeset |
| Context | `defmodule *Context`, `def list_*` | phoenix-context |
| GenServer | `use GenServer`, `handle_call` | genserver |
| Supervisor | `use Supervisor`, `start_link` | supervisor |
| Task | `Task.async`, `Task.Supervisor` | elixir-task |
| Oban Worker | `use Oban.Worker`, `perform/1` | oban-worker |
| Absinthe | `use Absinthe.Schema`, `field :` | graphql-schema |
| ExUnit Test | `use ExUnit.Case`, `test "` | exunit-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Controllers/LiveViews**: các trình xử lý HTTP/WebSocket
- **Contexts**: logic nghiệp vụ
- **Schemas**: các mô hình dữ liệu Ecto (Ecto models)
- **Channels**: các trình xử lý thời gian thực (real-time handlers)
- **Workers**: các tác vụ chạy nền (background jobs)

## Nguồn trích xuất lệnh (Command sources)
- Các bí danh (aliases) trong `mix.exs`
- README/docs, CI
- Các lệnh phổ biến: `mix deps.get`, `mix test`, `mix phx.server`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `lib/*/`, `lib/*_web/`
- `priv/repo/migrations/`
- `test/`
- `config/`
FILE:references/flutter.md
# Flutter/Dart

## Tín hiệu nhận diện
- `pubspec.yaml`
- `lib/main.dart`
- Các thư mục `android/`, `ios/`, `web/`
- `.dart_tool/`
- `analysis_options.yaml`

## Tín hiệu đa mô-đun (Multi-module signals)
- `melos.yaml` (monorepo)
- Nhiều tệp `pubspec.yaml` trong các thư mục con
- Thư mục `packages/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `pubspec.yaml` (các thư viện phụ thuộc)
- `analysis_options.yaml`
- `build.yaml` (nếu sử dụng build_runner)
- `lib/main.dart` (điểm khởi chạy ứng dụng - entry point)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `lib/`, `test/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`screens/`, `widgets/`, `models/`, `services/`, `providers/`, `repositories/`, `utils/`, `constants/`, `bloc/`, `cubit/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Screen/Page | `*Screen`, `*Page`, `extends StatefulWidget` | flutter-screen |
| Widget | `extends StatelessWidget`, `extends StatefulWidget` | flutter-widget |
| BLoC | `extends Bloc<`, `extends Cubit<` | bloc-pattern |
| Provider | `ChangeNotifier`, `Provider.of<`, `context.read<` | provider-pattern |
| Riverpod | `@riverpod`, `ref.watch`, `ConsumerWidget` | riverpod-provider |
| GetX | `GetxController`, `Get.put`, `Obx(` | getx-controller |
| Repository | `*Repository`, `abstract class *Repository` | data-repository |
| Service | `*Service` | service-layer |
| Model | `fromJson`, `toJson`, `@JsonSerializable` | json-model |
| Freezed | `@freezed`, `part '*.freezed.dart'` | freezed-model |
| API Client | `Dio`, `http.Client`, `Retrofit` | api-client |
| Navigation | `Navigator`, `GoRouter`, `auto_route` | flutter-navigation |
| Localization | `AppLocalizations`, `l10n`, `intl` | flutter-l10n |
| Testing | `testWidgets`, `WidgetTester`, `flutter_test` | widget-test |
| Integration Test | `integration_test`, `IntegrationTestWidgetsFlutterBinding` | integration-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Danh mục màn hình (Screens inventory)**: các thư mục dưới `screens/`, `pages/`
- **Quản lý trạng thái (State management)**: BLoC, Provider, Riverpod, GetX
- **Thiết lập điều hướng (Navigation setup)**: GoRouter, auto_route, Navigator
- **Phương pháp tiêm phụ thuộc (DI approach)**: get_it, injectable, thủ công (manual)
- **Tầng API (API layer)**: Dio, http, Retrofit
- **Các mô hình dữ liệu (Models)**: Freezed, json_serializable

## Nguồn trích xuất lệnh (Command sources)
- Các kịch bản (scripts) trong `pubspec.yaml` (nếu sử dụng melos)
- README/docs
- Các lệnh phổ biến: `flutter run`, `flutter test`, `flutter build`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `lib/`, `test/`
- `lib/screens/`, `lib/widgets/`
- `lib/bloc/`, `lib/providers/`
- `assets/`
FILE:references/generic.md
# Ngăn xếp Công nghệ Chung / Không xác định (Generic/Unknown Stack)

Tài liệu tham khảo dự phòng khi không phát hiện được nền tảng cụ thể nào.

## Tín hiệu nhận diện
- Không tìm thấy tệp biên dịch/cấu hình đặc thù nào
- Ngăn xếp công nghệ pha trộn (Mixed technology stack)
- Kho lưu trữ (repository) chỉ chứa tài liệu

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều thư mục tách biệt theo từng mối quan tâm (separate concerns)
- Các thư mục `packages/`, `modules/`, `libs/`
- Cấu trúc monorepo không sử dụng bộ công cụ đặc thù

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `README.md` (tổng quan dự án)
- `docs/*` (tài liệu)
- `.env.example` (các biến môi trường)
- `docker-compose.yml` (các dịch vụ - services)
- Các tệp CI (`.github/workflows/`, v.v.)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `lib/`, `app/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`api/`, `core/`, `utils/`, `services/`, `models/`, `config/`, `scripts/`

### Các dấu hiệu nhận biết mẫu chung (Generic pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Entry Point | `main.*`, `index.*`, `app.*` | entry-point |
| Config | `config.*`, `settings.*` | config-file |
| API Client | `api/`, `client/`, các lệnh gọi HTTP | api-client |
| Model | `model/`, `types/`, các cấu trúc dữ liệu | data-model |
| Service | `service/`, logic nghiệp vụ | service-layer |
| Utility | `utils/`, `helpers/`, `common/` | utility-module |
| Test | `test/`, `tests/`, `*_test.*`, `*.test.*` | test-file |
| Script | `scripts/`, `bin/` | script-file |
| Documentation | `docs/`, `*.md` | documentation |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Cấu trúc dự án (Project structure)**: các thư mục chính
- **Điểm khởi chạy (Entry points)**: các tệp chính
- **Cấu hình (Configuration)**: các tệp cấu hình
- **Thư viện phụ thuộc (Dependencies)**: bất kỳ trình quản lý gói nào
- **Các lệnh Build/Run**: trích xuất từ README/scripts

## Nguồn trích xuất lệnh (Command sources)
- `README.md` (tìm các khối mã - code blocks)
- `Makefile`, `Taskfile.yml`
- Thư mục `scripts/`
- Các luồng công việc CI (CI workflows)
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/`, `lib/`
- `docs/`
- `scripts/`
- `config/`

## Ghi chú

Khi sử dụng tài liệu tham khảo chung này:
1. Quét tìm bất kỳ mẫu kiến trúc nào có thể nhận diện được
2. Ghi chép lại cấu trúc dự án thực tế tìm thấy
3. Trích xuất các lệnh từ README nếu có sẵn
4. Ghi chú lại bất kỳ công nghệ nào được nhắc đến trong tài liệu (docs)
5. Giữ cho đầu ra tối giản và bám sát thực tế
FILE:references/go.md
# Go

## Tín hiệu nhận diện
- `go.mod`
- `go.sum`
- `main.go`
- Các thư mục `cmd/`, `internal/`, `pkg/`

## Tín hiệu đa mô-đun (Multi-module signals)
- `go.work` (workspace)
- Nhiều tệp `go.mod`
- `cmd/*/main.go` (nhiều tệp thực thi binary)

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `go.mod` (các gói phụ thuộc)
- `Makefile` (các lệnh biên dịch)
- `config/*.yaml` hoặc `*.toml`

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `cmd/`, `internal/`, `pkg/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`handler/`, `service/`, `repository/`, `model/`, `middleware/`, `config/`, `util/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| HTTP Handler | `http.Handler`, `http.HandlerFunc`, `gin.Context` | http-handler |
| Gin Route | `gin.Engine`, `r.GET(`, `r.POST(` | gin-route |
| Echo Route | `echo.Echo`, `e.GET(`, `e.POST(` | echo-route |
| Fiber Route | `fiber.App`, `app.Get(`, `app.Post(` | fiber-route |
| gRPC Service | `*.proto`, `pb.*Server` | grpc-service |
| Repository | `type *Repository interface`, `*Repository` | data-repository |
| Service | `type *Service interface`, `*Service` | service-layer |
| GORM Model | `gorm.Model`, `*gorm.DB` | gorm-model |
| sqlx | `sqlx.DB`, `sqlx.NamedExec` | sqlx-usage |
| Migration | `goose`, `golang-migrate` | db-migration |
| Middleware | `func(*Context)`, `middleware.*` | go-middleware |
| Worker | `go func()`, `sync.WaitGroup`, `errgroup` | worker-goroutine |
| Config | `viper`, `envconfig`, `cleanenv` | config-loader |
| Unit Test | `*_test.go`, `func Test*(t *testing.T)` | go-test |
| Mock | `mockgen`, `*_mock.go` | go-mock |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **HTTP handlers**: các điểm cuối API (API endpoints)
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu
- **Models**: các cấu trúc dữ liệu (data structures)
- **Middleware**: các bộ chặn xử lý yêu cầu (request interceptors)
- **Migrations**: các bản di trú cơ sở dữ liệu (database migrations)

## Nguồn trích xuất lệnh (Command sources)
- Các mục tiêu trong `Makefile`
- README/docs, CI
- Các lệnh phổ biến: `go build`, `go test`, `go run`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `cmd/`, `internal/`, `pkg/`
- `api/`, `handler/`
- `migrations/`
- `config/`
FILE:references/ios.md
# iOS (Xcode/Swift)

## Tín hiệu nhận diện
- `*.xcodeproj`, `*.xcworkspace`
- `Package.swift` (SPM)
- `Podfile`, `Podfile.lock` (CocoaPods)
- `Cartfile` (Carthage)
- `*.pbxproj`
- `Info.plist`

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều mục tiêu (targets) trong `*.xcodeproj`
- Nhiều tệp `Package.swift`
- Workspace chứa nhiều dự án (projects)
- Các thư mục `Modules/`, `Packages/`, `Features/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `*.xcodeproj/project.pbxproj` (danh sách target)
- `Package.swift` (các gói phụ thuộc, targets)
- `Podfile` (các gói phụ thuộc)
- `*.xcconfig` (cấu hình biên dịch - build configs)
- Các tệp `Info.plist`

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `*/Sources/`, `*/Source/`
- `*/App/`, `*/Core/`, `*/Features/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`Models/`, `Views/`, `ViewModels/`, `Services/`, `Networking/`, `Utilities/`, `Extensions/`, `Coordinators/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| SwiftUI View | `struct *: View`, `var body: some View` | swiftui-view |
| UIKit VC | `UIViewController`, `viewDidLoad()` | uikit-viewcontroller |
| ViewModel | `@Observable`, `ObservableObject`, `@Published` | viewmodel-observable |
| Coordinator | `Coordinator`, `*Coordinator` | coordinator-pattern |
| Repository | `*Repository`, `protocol *Repository` | data-repository |
| Service | `*Service`, `protocol *Service` | service-layer |
| Core Data | `NSManagedObject`, `@NSManaged`, `.xcdatamodeld` | coredata-entity |
| Realm | `Object`, `@Persisted` | realm-model |
| Network | `URLSession`, `Alamofire`, `Moya` | network-client |
| Dependency | `@Inject`, `Container`, `Swinject` | di-container |
| Navigation | `NavigationStack`, `NavigationPath` | navigation-swiftui |
| Combine | `Publisher`, `AnyPublisher`, `sink` | combine-publisher |
| Async/Await | `async`, `await`, `Task {` | async-await |
| Unit Test | `XCTestCase`, `func test*()` | xctest |
| UI Test | `XCUIApplication`, `XCUIElement` | xcuitest |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Danh mục targets (Targets inventory)**: danh sách trích xuất từ pbxproj
- **Modules/Packages**: các gói SPM, Pods
- **Kiến trúc View (View architecture)**: SwiftUI so với UIKit
- **Quản lý trạng thái (State management)**: Combine, Observable, v.v.
- **Tầng mạng (Networking layer)**: URLSession, Alamofire, v.v.
- **Lưu trữ bền vững (Persistence)**: Core Data, Realm, UserDefaults
- **Thiết lập DI (DI setup)**: Swinject, tiêm phụ thuộc thủ công (manual injection)

## Nguồn trích xuất lệnh (Command sources)
- Tài liệu README/docs có chứa các lệnh xcodebuild
- Các lane trong `fastlane/Fastfile`
- Các luồng công việc CI (`.github/workflows/`, `.gitlab-ci.yml`)
- Các lệnh phổ biến: `xcodebuild test`, `fastlane test`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `*/Sources/`, `*/Tests/`
- `*.xcodeproj/`, `*.xcworkspace/`
- `Pods/` (nếu sử dụng CocoaPods)
- `Packages/` (nếu sử dụng các gói SPM cục bộ)
FILE:references/java.md
# Java/JVM (Spring, v.v.)

## Tín hiệu nhận diện
- `pom.xml` (Maven)
- `build.gradle`, `build.gradle.kts` (Gradle)
- `settings.gradle` (đa mô-đun - multi-module)
- `src/main/java/`, `src/main/kotlin/`
- `application.properties`, `application.yml`

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều tệp `pom.xml` có thẻ `<modules>`
- Nhiều tệp `build.gradle` có lệnh `include()`
- Các thư mục `modules/`, `services/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `pom.xml` hoặc `build.gradle*` (các thư viện phụ thuộc)
- `application.properties/yml` (cấu hình)
- `settings.gradle` (danh sách mô-đun)
- `docker-compose.yml` (các dịch vụ - services)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/main/java/`, `src/main/kotlin/`
- `src/test/java/`, `src/test/kotlin/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`controller/`, `service/`, `repository/`, `model/`, `entity/`, `dto/`, `config/`, `exception/`, `util/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| REST Controller | `@RestController`, `@GetMapping`, `@PostMapping` | spring-controller |
| Service | `@Service`, `class *Service` | spring-service |
| Repository | `@Repository`, `JpaRepository`, `CrudRepository` | spring-repository |
| Entity | `@Entity`, `@Table`, `@Id` | jpa-entity |
| DTO | `class *DTO`, `class *Request`, `class *Response` | dto-pattern |
| Config | `@Configuration`, `@Bean` | spring-config |
| Component | `@Component`, `@Autowired` | spring-component |
| Security | `@EnableWebSecurity`, `SecurityFilterChain` | spring-security |
| Validation | `@Valid`, `@NotNull`, `@Size` | validation-pattern |
| Exception Handler | `@ControllerAdvice`, `@ExceptionHandler` | exception-handler |
| Scheduler | `@Scheduled`, `@EnableScheduling` | scheduled-task |
| Event | `ApplicationEvent`, `@EventListener` | event-listener |
| Flyway Migration | `V*__*.sql`, `flyway` | flyway-migration |
| Liquibase | `changelog*.xml`, `liquibase` | liquibase-migration |
| Unit Test | `@Test`, `@SpringBootTest`, `MockMvc` | spring-test |
| Integration Test | `@DataJpaTest`, `@WebMvcTest` | integration-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối REST (REST endpoints)
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu (JPA, JDBC)
- **Entities/DTOs**: các mô hình dữ liệu (data models)
- **Configuration**: các Spring beans, cấu hình theo môi trường (profiles)
- **Security**: cấu hình xác thực/phân quyền (auth config)

## Nguồn trích xuất lệnh (Command sources)
- Các plugin trong `pom.xml`, các tác vụ (tasks) trong `build.gradle`
- README/docs, CI
- Các lệnh phổ biến: `./mvnw`, `./gradlew`, `mvn test`, `gradle test`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/main/java/`, `src/main/kotlin/`
- `src/main/resources/`
- `src/test/`
- `db/migration/` (Flyway)
FILE:references/node.md
# Node.js

## Tín hiệu nhận diện
- `package.json` (không chứa react/react-native)
- `tsconfig.json`
- `node_modules/`
- Các tệp khởi chạy `*.js`, `*.ts`, `*.mjs`, `*.cjs`

## Tín hiệu đa mô-đun (Multi-module signals)
- `pnpm-workspace.yaml`, `lerna.json`
- `nx.json`, `turbo.json`
- Nhiều tệp `package.json` trong các thư mục con
- Các thư mục `packages/`, `apps/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `package.json` (các gói phụ thuộc, kịch bản scripts)
- `tsconfig.json` (đường dẫn paths, tùy chọn trình biên dịch)
- `.env.example` (các biến môi trường)
- `docker-compose.yml` (các dịch vụ - services)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `lib/`, `app/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`controllers/`, `services/`, `models/`, `routes/`, `middleware/`, `utils/`, `config/`, `types/`, `repositories/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Express Route | `app.get(`, `app.post(`, `Router()` | express-route |
| Express Middleware | `(req, res, next)`, `app.use(` | express-middleware |
| NestJS Controller | `@Controller`, `@Get`, `@Post` | nestjs-controller |
| NestJS Service | `@Injectable`, `@Service` | nestjs-service |
| NestJS Module | `@Module`, `imports:`, `providers:` | nestjs-module |
| Fastify Route | `fastify.get(`, `fastify.post(` | fastify-route |
| GraphQL Resolver | `@Resolver`, `@Query`, `@Mutation` | graphql-resolver |
| TypeORM Entity | `@Entity`, `@Column`, `@PrimaryGeneratedColumn` | typeorm-entity |
| Prisma Model | `prisma.*.create`, `prisma.*.findMany` | prisma-usage |
| Mongoose Model | `mongoose.Schema`, `mongoose.model(` | mongoose-model |
| Sequelize Model | `Model.init`, `DataTypes` | sequelize-model |
| Queue Worker | `Bull`, `BullMQ`, `process(` | queue-worker |
| Tác vụ định kỳ (Cron Job) | `@Cron`, `node-cron`, `cron.schedule` | cron-job |
| WebSocket | `ws`, `socket.io`, `io.on(` | websocket-handler |
| Kiểm thử đơn vị (Unit Test) | `describe(`, `it(`, `expect(`, `jest` | jest-test |
| Kiểm thử đầu cuối (E2E Test) | `supertest`, `request(app)` | e2e-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Routes/controllers**: các điểm cuối (endpoints) API
- **Tầng Services**: logic nghiệp vụ
- **Cơ sở dữ liệu (Database)**: cách sử dụng ORM/ODM (TypeORM, Prisma, Mongoose)
- **Middleware**: xác thực (auth), kiểm tra dữ liệu (validation), xử lý lỗi
- **Tác vụ chạy ngầm (Background jobs)**: hàng đợi (queues), tác vụ định kỳ (cron jobs)
- **Trình xử lý WebSocket (WebSocket handlers)**: các tính năng thời gian thực

## Nguồn câu lệnh
- Mục scripts trong `package.json`
- Tệp README/tài liệu (docs)
- Các luồng công việc CI (CI workflows)
- Phổ biến: `npm run dev`, `npm run build`, `npm test`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn (repo)

## Các đường dẫn chính
- `src/`, `lib/`
- `src/routes/`, `src/controllers/`
- `src/services/`, `src/models/`
- `prisma/`, `migrations/`
FILE:references/php.md
# PHP

## Dấu hiệu nhận diện
- `composer.json`, `composer.lock`
- `public/index.php`
- `artisan` (Laravel)
- `spark` (CodeIgniter 4)
- `bin/console` (Symfony)
- `app/Config/App.php` (CodeIgniter 4)
- `ext-phalcon` trong composer.json (Phalcon)
- `phalcon/devtools` (Phalcon)

## Dấu hiệu đa mô-đun (Multi-module)
- Thư mục `packages/`
- Các mô-đun Laravel (`app/Modules/`)
- Các mô-đun CodeIgniter (`app/Modules/`, `modules/`)
- Phalcon đa ứng dụng (`apps/*/`)
- Nhiều tệp `composer.json` trong các thư mục con

## Nguồn phân tích trước khi tạo
- `composer.json` (các gói phụ thuộc)
- `.env.example` (các biến môi trường)
- `config/*.php` (Laravel/Symfony)
- `routes/*.php` (Laravel)
- `app/Config/*` (CodeIgniter 4)
- `apps/*/config/` (Phalcon)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `app/`, `src/`, `apps/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`Controllers/`, `Services/`, `Repositories/`, `Models/`, `Entities/`, `Http/`, `Providers/`, `Console/`

### Cấu trúc đặc thù theo từng Framework

**Laravel** (ghi nhận nếu có mặt):
- `app/Http/Controllers`, `app/Models`, `database/migrations`
- `routes/*.php`, `resources/views`

**Symfony** (ghi nhận nếu có mặt):
- `src/Controller`, `src/Entity`, `config/packages`, `templates`

**CodeIgniter 4** (ghi nhận nếu có mặt):
- `app/Controllers`, `app/Models`, `app/Views`
- `app/Config/Routes.php`, `app/Database/Migrations`

**Phalcon** (ghi nhận nếu có mặt):
- `apps/*/controllers/`, `apps/*/Module.php`
- `models/`, `views/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Laravel Controller | `extends Controller`, `public function index` | laravel-controller |
| Laravel Model | `extends Model`, `protected $fillable` | laravel-model |
| Laravel Migration | `extends Migration`, `Schema::create` | laravel-migration |
| Laravel Service | `class *Service`, `app/Services/` | laravel-service |
| Laravel Repository | `*Repository`, `interface *Repository` | laravel-repository |
| Laravel Job | `implements ShouldQueue`, `dispatch(` | laravel-job |
| Laravel Event | `extends Event`, `event(` | laravel-event |
| Symfony Controller | `#[Route]`, `AbstractController` | symfony-controller |
| Symfony Service | `#[AsService]`, `services.yaml` | symfony-service |
| Doctrine Entity | `#[ORM\Entity]`, `#[ORM\Column]` | doctrine-entity |
| Doctrine Migration | `AbstractMigration`, `$this->addSql` | doctrine-migration |
| CI4 Controller | `extends BaseController`, `app/Controllers/` | ci4-controller |
| CI4 Model | `extends Model`, `protected $table` | ci4-model |
| CI4 Migration | `extends Migration`, `$this->forge->` | ci4-migration |
| CI4 Entity | `extends Entity`, `app/Entities/` | ci4-entity |
| Phalcon Controller | `extends Controller`, `Phalcon\Mvc\Controller` | phalcon-controller |
| Phalcon Model | `extends Model`, `Phalcon\Mvc\Model` | phalcon-model |
| Phalcon Migration | `Phalcon\Migrations`, `morphTable` | phalcon-migration |
| API Resource | `extends JsonResource`, `toArray` | api-resource |
| Form Request | `extends FormRequest`, `rules()` | form-request |
| Middleware | `implements Middleware`, `handle(` | php-middleware |
| Unit Test | `extends TestCase`, `test*()`, `PHPUnit` | phpunit-test |
| Feature Test | `extends TestCase`, `$this->get(`, `$this->post(` | feature-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối (endpoints) HTTP
- **Models/Entities**: tầng dữ liệu
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu
- **Migrations**: các thay đổi cơ sở dữ liệu
- **Jobs/Events**: xử lý bất đồng bộ
- **Các mô-đun nghiệp vụ (Business modules)**: các mô-đun lớn nhất theo quy mô

## Nguồn câu lệnh
- Mục scripts trong `composer.json`
- `php artisan` (Laravel)
- `php spark` (CodeIgniter 4)
- `bin/console` (Symfony)
- Các lệnh công cụ phát triển `phalcon`
- README/docs, CI
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính

**Laravel:**
- `app/`, `routes/`, `database/migrations/`
- `resources/views/`, `tests/`

**Symfony:**
- `src/`, `config/`, `templates/`
- `migrations/`, `tests/`

**CodeIgniter 4:**
- `app/Controllers/`, `app/Models/`, `app/Views/`
- `app/Database/Migrations/`, `tests/`

**Phalcon:**
- `apps/*/controllers/`, `apps/*/models/`
- `apps/*/views/`, `migrations/`
FILE:references/python.md
# Python

## Dấu hiệu nhận diện
- `pyproject.toml`
- `requirements.txt`, `requirements-dev.txt`
- `Pipfile`, `poetry.lock`
- `setup.py`, `setup.cfg`
- `manage.py` (Django)

## Dấu hiệu đa mô-đun (Multi-module)
- Nhiều tệp `pyproject.toml` trong các thư mục con
- Các thư mục `packages/`, `apps/`
- Thư mục `apps/` kiểu Django có chứa `apps.py`

## Nguồn phân tích trước khi tạo
- `pyproject.toml` hoặc `setup.py`
- `requirements*.txt`, `Pipfile`
- `tox.ini`, `pytest.ini`
- `manage.py`, `settings.py` (Django)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `app/`, `packages/`, `tests/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`api/`, `routers/`, `views/`, `services/`, `repositories/`, `models/`, `schemas/`, `utils/`, `config/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| FastAPI Router | `APIRouter`, `@router.get`, `@router.post` | fastapi-router |
| FastAPI Dependency | `Depends(`, `def get_*():` | fastapi-dependency |
| Django View | `View`, `APIView`, `def get(self, request)` | django-view |
| Django Model | `models.Model`, `class Meta:` | django-model |
| Django Serializer | `serializers.Serializer`, `ModelSerializer` | drf-serializer |
| Flask Route | `@app.route`, `Blueprint` | flask-route |
| Pydantic Model | `BaseModel`, `Field(`, `model_validator` | pydantic-model |
| SQLAlchemy Model | `Base`, `Column(`, `relationship(` | sqlalchemy-model |
| Alembic Migration | `alembic/versions/`, `op.create_table` | alembic-migration |
| Repository | `*Repository`, `class *Repository` | data-repository |
| Service | `*Service`, `class *Service` | service-layer |
| Celery Task | `@celery.task`, `@shared_task` | celery-task |
| CLI Command | `@click.command`, `typer.Typer` | cli-command |
| Unit Test | `pytest`, `def test_*():`, `unittest` | pytest-test |
| Fixture | `@pytest.fixture`, `conftest.py` | pytest-fixture |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Routers/views**: các điểm cuối (endpoints) API
- **Models/schemas**: các mô hình dữ liệu (Pydantic, SQLAlchemy, Django)
- **Services**: tầng logic nghiệp vụ
- **Repositories**: tầng truy cập dữ liệu
- **Migrations**: các bản di trú cơ sở dữ liệu Alembic, Django
- **Tasks**: Celery, các tác vụ chạy ngầm

## Nguồn câu lệnh
- Các mục cấu hình công cụ trong `pyproject.toml`
- README/docs, CI
- Phổ biến: `python manage.py`, `pytest`, `uvicorn`, `flask run`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/`, `app/`
- `tests/`
- `alembic/`, `migrations/`
- `templates/`, `static/` (nếu là ứng dụng web)
FILE:references/react-native.md
# React Native

## Dấu hiệu nhận diện
- `package.json` có chứa `react-native`
- `metro.config.js`
- `app.json` hoặc `app.config.js` (Expo)
- Các thư mục `android/`, `ios/`
- `babel.config.js` có cấu hình metro preset

## Dấu hiệu đa mô-đun (Multi-module)
- Monorepo có thư mục `packages/`
- Nhiều tệp `app.json`
- Không gian làm việc Nx (Nx workspace) có sử dụng React Native

## Nguồn phân tích trước khi tạo
- `package.json` (các gói phụ thuộc, scripts)
- `app.json` hoặc `app.config.js`
- `metro.config.js`
- `babel.config.js`
- `tsconfig.json`

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `app/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`screens/`, `components/`, `navigation/`, `services/`, `hooks/`, `store/`, `api/`, `utils/`, `assets/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Screen | `*Screen`, `export function *Screen` | rn-screen |
| Component | `export function *()`, `StyleSheet.create` | rn-component |
| Navigation | `createNativeStackNavigator`, `NavigationContainer` | rn-navigation |
| Hook | `use*`, `export function use*()` | rn-hook |
| Redux | `createSlice`, `configureStore` | redux-slice |
| Zustand | `create(`, `useStore` | zustand-store |
| React Query | `useQuery`, `useMutation` | react-query |
| Native Module | `NativeModules`, `TurboModule` | native-module |
| Async Storage | `AsyncStorage`, `@react-native-async-storage` | async-storage |
| SQLite | `expo-sqlite`, `react-native-sqlite-storage` | sqlite-storage |
| Push Notification | `@react-native-firebase/messaging`, `expo-notifications` | push-notification |
| Deep Link | `Linking`, `useURL`, `expo-linking` | deep-link |
| Animation | `Animated`, `react-native-reanimated` | rn-animation |
| Gesture | `react-native-gesture-handler`, `Gesture` | rn-gesture |
| Testing | `@testing-library/react-native`, `render` | rntl-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Danh mục màn hình (Screens inventory)**: các thư mục con nằm dưới `screens/`
- **Cấu trúc điều hướng (Navigation structure)**: các bộ điều hướng stack, tab, drawer
- **Quản lý trạng thái (State management)**: Redux, Zustand, Context
- **Mô-đun bản địa (Native modules)**: mã nguồn native tùy chỉnh
- **Tầng lưu trữ (Storage layer)**: AsyncStorage, SQLite, MMKV
- **Đặc thù theo nền tảng (Platform-specific)**: `*.android.tsx`, `*.ios.tsx`

## Nguồn câu lệnh
- Mục scripts trong `package.json`
- README/docs
- Phổ biến: `npm run android`, `npm run ios`, `npx expo start`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/screens/`, `src/components/`
- `src/navigation/`, `src/store/`
- `android/app/`, `ios/*/`
- `assets/`
FILE:references/react-web.md
# React (Web)

## Dấu hiệu nhận diện
- `package.json` có chứa `react`, `react-dom`
- `vite.config.ts`, `next.config.js`, `craco.config.js`
- `tsconfig.json` hoặc `jsconfig.json`
- `src/App.tsx` hoặc `src/App.jsx`
- `public/index.html` (CRA)

## Dấu hiệu đa mô-đun (Multi-module)
- `pnpm-workspace.yaml`, `lerna.json`
- Nhiều tệp `package.json` trong các thư mục con
- Các thư mục `packages/`, `apps/`
- Không gian làm việc Nx (`nx.json`)

## Nguồn phân tích trước khi tạo
- `package.json` (các gói phụ thuộc, scripts)
- `tsconfig.json` (đường dẫn paths, tùy chọn trình biên dịch)
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `.env.example` (các biến môi trường)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `app/`, `pages/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`components/`, `hooks/`, `services/`, `utils/`, `store/`, `api/`, `types/`, `contexts/`, `features/`, `layouts/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Component | `export function *()`, `export const * =` có chứa JSX | react-component |
| Hook | `use*`, `export function use*()` | custom-hook |
| Context | `createContext`, `useContext`, `*Provider` | react-context |
| Redux | `createSlice`, `configureStore`, `useSelector` | redux-slice |
| Zustand | `create(`, `useStore` | zustand-store |
| React Query | `useQuery`, `useMutation`, `QueryClient` | react-query |
| Form | `useForm`, `react-hook-form`, `Formik` | form-handling |
| Router | `createBrowserRouter`, `Route`, `useNavigate` | react-router |
| API Client | `axios`, `fetch`, `ky` | api-client |
| Testing | `@testing-library/react`, `render`, `screen` | rtl-test |
| Storybook | `*.stories.tsx`, `Meta`, `StoryObj` | storybook |
| Styled | `styled-components`, `@emotion`, `styled(` | styled-component |
| Tailwind | `className="*"`, `tailwind.config.js` | tailwind-usage |
| i18n | `useTranslation`, `i18next`, `t()` | i18n-usage |
| Auth | `useAuth`, `AuthProvider`, `PrivateRoute` | auth-pattern |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Danh mục thành phần (Components inventory)**: các thư mục con dưới `components/`
- **Tính năng/trang (Features/pages)**: các thư mục con dưới `features/`, `pages/`
- **Quản lý trạng thái (State management)**: Redux, Zustand, Context
- **Thiết lập định tuyến (Routing setup)**: React Router, các trang Next.js
- **Tầng API (API layer)**: các thực thể axios, hàm bọc fetch
- **Phương pháp định kiểu (Styling approach)**: CSS modules, Tailwind, styled-components
- **Xử lý biểu mẫu (Form handling)**: react-hook-form, Formik

## Nguồn câu lệnh
- Mục scripts trong `package.json`
- README/docs
- Các luồng công việc CI (CI workflows)
- Phổ biến: `npm run dev`, `npm run build`, `npm test`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/components/`, `src/hooks/`
- `src/pages/`, `src/features/`
- `src/store/`, `src/api/`
- `public/`, `dist/`, `build/`
FILE:references/ruby.md
# Ruby/Rails

## Dấu hiệu nhận diện
- `Gemfile`
- `Gemfile.lock`
- `config.ru`
- `Rakefile`
- `config/application.rb` (Rails)

## Dấu hiệu đa mô-đun (Multi-module)
- Nhiều tệp `Gemfile` trong các thư mục con
- Thư mục `engines/` (Rails engines)
- Thư mục `gems/` (monorepo)

## Nguồn phân tích trước khi tạo
- `Gemfile` (các gói phụ thuộc)
- `config/database.yml`
- `config/routes.rb` (Rails)
- `.env.example`

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `app/`, `lib/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`controllers/`, `models/`, `services/`, `jobs/`, `mailers/`, `channels/`, `helpers/`, `concerns/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Rails Controller | `< ApplicationController`, `def index` | rails-controller |
| Rails Model | `< ApplicationRecord`, `has_many`, `belongs_to` | rails-model |
| Rails Migration | `< ActiveRecord::Migration`, `create_table` | rails-migration |
| Service Object | `class *Service`, `def call` | service-object |
| Rails Job | `< ApplicationJob`, `perform_later` | rails-job |
| Mailer | `< ApplicationMailer`, `mail(` | rails-mailer |
| Channel | `< ApplicationCable::Channel` | action-cable |
| Serializer | `< ActiveModel::Serializer`, `attributes` | serializer |
| Concern | `extend ActiveSupport::Concern` | rails-concern |
| Sidekiq Worker | `include Sidekiq::Worker`, `perform_async` | sidekiq-worker |
| Grape API | `Grape::API`, `resource :` | grape-api |
| RSpec Test | `RSpec.describe`, `it "` | rspec-test |
| Factory | `FactoryBot.define`, `factory :` | factory-bot |
| Rake Task | `task :`, `namespace :` | rake-task |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối (endpoints) HTTP
- **Models**: các mối quan hệ liên kết ActiveRecord
- **Services**: logic nghiệp vụ
- **Jobs**: xử lý tác vụ chạy ngầm
- **Migrations**: lược đồ cơ sở dữ liệu

## Nguồn câu lệnh
- Các script trong `Gemfile`
- Các tác vụ trong `Rakefile`
- `bin/rails`, `bin/rake`
- README/docs, CI
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `app/controllers/`, `app/models/`
- `app/services/`, `app/jobs/`
- `db/migrate/`
- `spec/`, `test/`
- `lib/`
FILE:references/rust.md
# Rust

## Dấu hiệu nhận diện
- `Cargo.toml`
- `Cargo.lock`
- `src/main.rs` hoặc `src/lib.rs`
- Thư mục `target/`

## Dấu hiệu đa mô-đun (Multi-module)
- `[workspace]` trong `Cargo.toml`
- Nhiều tệp `Cargo.toml` trong các thư mục con
- Các thư mục `crates/`, `packages/`

## Nguồn phân tích trước khi tạo
- `Cargo.toml` (các gói phụ thuộc, tính năng features)
- `build.rs` (script biên dịch)
- `rust-toolchain.toml` (bộ công cụ toolchain)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `crates/*/src/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`handlers/`, `services/`, `models/`, `db/`, `api/`, `utils/`, `error/`, `config/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Axum Handler | `axum::`, `Router`, `async fn handler` | axum-handler |
| Actix Route | `actix_web::`, `#[get]`, `#[post]` | actix-route |
| Rocket Route | `rocket::`, `#[get]`, `#[post]` | rocket-route |
| Service | `impl *Service`, `pub struct *Service` | rust-service |
| Repository | `*Repository`, `trait *Repository` | rust-repository |
| Diesel Model | `diesel::`, `Queryable`, `Insertable` | diesel-model |
| SQLx | `sqlx::`, `FromRow`, `query_as!` | sqlx-model |
| SeaORM | `sea_orm::`, `Entity`, `ActiveModel` | seaorm-entity |
| Error Type | `thiserror`, `anyhow`, `#[derive(Error)]` | error-type |
| CLI | `clap`, `#[derive(Parser)]` | cli-app |
| Async Task | `tokio::spawn`, `async fn` | async-task |
| Trait | `pub trait *`, `impl * for` | rust-trait |
| Unit Test | `#[cfg(test)]`, `#[test]` | rust-test |
| Integration Test | `tests/`, `#[tokio::test]` | integration-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Handlers/routes**: các điểm cuối (endpoints) API
- **Services**: logic nghiệp vụ
- **Models/entities**: các cấu trúc dữ liệu
- **Kiểu lỗi (Error types)**: các kiểu lỗi tùy chỉnh
- **Migrations**: các bản di trú dữ liệu diesel/sqlx

## Nguồn câu lệnh
- Các script/bí danh (aliases) trong `Cargo.toml`
- `Makefile`, README/docs
- Phổ biến: `cargo build`, `cargo test`, `cargo run`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/`, `crates/`
- `tests/`
- `migrations/`
- `examples/`

---
name: supabase-principal-architect-infrastructure-optimization
description: Đóng vai Kiến trúc sư Trưởng Supabase (Supabase Principal Architect). Xây dựng và tối ưu hóa hạ tầng Postgres/Edge sẵn sàng cho môi trường production. Trách nhiệm của bạn bao gồm chạy pg_cron để kiểm toán lược đồ (schemas), xử lý các khoảng trống chưa đồng bộ trong chính sách bảo mật cấp dòng (RLS), loại bỏ các chỉ mục (indexes) không sử dụng và tự động sinh định nghĩa đánh chỉ mục mục tiêu. Ngoài ra, xây dựng các bảng phát sóng thời gian thực (real-time broadcast tables) để theo dõi trạng thái xuyên suốt OpenHands, các luồng lưu trữ Obsidian, Hermes, KAI9000, LangGraph và GitHub workflows. Triển khai Edge Functions để quản lý các webhook động
---

# Tối ưu hóa Hạ tầng theo chuẩn Kiến trúc sư Trưởng Supabase

Mô tả chức năng của kỹ năng này và cách tác nhân (agent) nên sử dụng nó.

## Hướng dẫn

- Bước 1: ...
- Bước 2: ...

# Phong cách (taste) Terraform của một kỹ sư nền tảng đám mây
- Ghim cố định (pin) phiên bản Terraform và mọi phiên bản provider, đồng thời commit tệp .terraform.lock.hcl. Độ tin cậy: 0.95
- Lưu trữ trạng thái (state) từ xa có bật cơ chế khóa (locking), ví dụ như dùng S3 kết hợp với DynamoDB hoặc Terraform Cloud. Độ tin cậy: 0.95
- Tách biệt trạng thái theo từng môi trường và từng hệ thống để một lệnh apply không bao giờ tác động đến toàn bộ mọi thứ. Độ tin cậy: 0.90
- Sử dụng các thư mục riêng biệt cho từng môi trường thay vì dùng Terraform workspaces cho môi trường prod và staging. Độ tin cậy: 0.75
- Giữ cho các module nhỏ gọn và chỉ tập trung vào một mối quan tâm duy nhất, chẳng hạn như mạng (network) hoặc cơ sở dữ liệu (database). Độ tin cậy: 0.85
- Ghim cố định nguồn module vào một thẻ (tag) hoặc phiên bản cụ thể, không bao giờ trỏ vào một nhánh (branch) đang thay đổi. Độ tin cậy: 0.90
- Cung cấp kiểu dữ liệu (type) và mô tả (description) cho mọi biến, đồng thời thêm các khối xác thực (validation blocks) cho các đầu vào có rủi ro. Độ tin cậy: 0.85
- Chỉ xuất (expose) những đầu ra (outputs) mà các stack khác thực sự sử dụng. Độ tin cậy: 0.70
- Đặt tên tài nguyên theo kiểu snake_case và tránh lặp lại loại tài nguyên trong tên. Độ tin cậy: 0.75
- Áp dụng bộ thẻ (tag) dùng chung (owner, environment, cost center) thông qua cấu hình default_tags của provider. Độ tin cậy: 0.85
- Ưu tiên dùng for_each hơn count để việc thêm hoặc xóa một mục không làm xáo trộn địa chỉ tài nguyên. Độ tin cậy: 0.90
- Sử dụng các khối moved khi tái cấu trúc mã (refactor) thay vì chạy lệnh terraform state mv thủ công. Độ tin cậy: 0.85
- Đưa các tài nguyên hiện có vào quản lý bằng các khối import được đánh giá (review) thông qua pull request. Độ tin cậy: 0.80
- Chạy terraform fmt, validate và tflint trong hệ thống CI trên mọi pull request. Độ tin cậy: 0.90
- Đăng kết quả đầu ra của lệnh terraform plan dưới dạng bình luận trong pull request để thuận tiện cho việc đánh giá. Độ tin cậy: 0.85
- Chỉ chạy lệnh apply từ hệ thống CI bằng tệp plan đã được duyệt, không bao giờ chạy trực tiếp từ máy tính cá nhân. Độ tin cậy: 0.85
- Xác thực hệ thống CI với đám mây bằng OIDC thay vì sử dụng các khóa truy cập (access keys) tồn tại lâu dài. Độ tin cậy: 0.90
- Không bao giờ đặt thông tin bí mật (secrets) trong tệp tfvars; hãy đọc chúng từ trình quản lý bí mật (secrets manager) tại thời điểm apply. Độ tin cậy: 0.90
- Sử dụng prevent_destroy trên các tài nguyên lưu trữ trạng thái (stateful) như cơ sở dữ liệu và bucket. Độ tin cậy: 0.80
- Quét cấu hình bằng công cụ kiểm tra chính sách như checkov hoặc tfsec trước khi gộp mã (merge). Độ tin cậy: 0.75
- Tránh sử dụng provisioners và local-exec; hãy chuyển giao việc cấu hình cho các image hoặc công cụ quản lý cấu hình chuyên dụng. Độ tin cậy: 0.80
- Chạy lệnh plan theo lịch trình định kỳ để phát hiện sai lệch cấu hình (drift) và cảnh báo khi kết quả không trống. Độ tin cậy: 0.75
- Sử dụng data sources để tra cứu thông tin và tránh gán cứng (hardcode) các ID hoặc ARN. Độ tin cậy: 0.80

# Gu vận hành Kubernetes của một đội ngũ kỹ thuật nền tảng (platform team)
- Triển khai mọi thứ thông qua GitOps (Argo CD hoặc Flux); không ai chạy lệnh kubectl apply trực tiếp lên môi trường production bằng tay. Độ tin cậy: 0.90
- Đóng gói các dịch vụ dùng chung bằng Helm hoặc Kustomize, nhưng giữ cho các lớp cấu hình ghi đè (overlays) theo từng môi trường luôn nhỏ gọn và dễ đọc. Độ tin cậy: 0.80
- Thiết lập mức yêu cầu (requests) về CPU và bộ nhớ trên mọi container, và đặt giới hạn (limit) bộ nhớ bằng đúng mức request. Độ tin cậy: 0.90
- Tránh đặt giới hạn trần CPU (CPU limits) trên các dịch vụ nhạy cảm với độ trễ; hãy dựa vào thông số requests và việc tính toán kích thước node để ngăn chặn tình trạng bóp băng thông xử lý (throttling). Độ tin cậy: 0.70
- Trang bị readiness probe cho mọi Deployment; chỉ thêm liveness probe khi ứng dụng thực sự có nguy cơ rơi vào trạng thái treo cứng (deadlock). Độ tin cậy: 0.85
- Sử dụng startup probe cho các ứng dụng khởi động chậm thay vì đặt giá trị initialDelaySeconds quá dài trên liveness probe. Độ tin cậy: 0.80
- Chạy ít nhất hai bản sao (replicas) đứng sau một PodDisruptionBudget đối với bất kỳ dịch vụ nào mà người dùng phụ thuộc vào. Độ tin cậy: 0.90
- Phân bổ đều các bản sao qua nhiều vùng khả dụng (zones) bằng cách sử dụng topologySpreadConstraints. Độ tin cậy: 0.80
- Ghim cố định các image bằng mã băm (digest) hoặc một thẻ phiên bản bất biến (immutable version tag), tuyệt đối không bao giờ dùng thẻ latest. Độ tin cậy: 0.95
- Chạy các container dưới quyền người dùng không phải root (non-root) với hệ thống tệp gốc chỉ đọc (read-only root filesystem) và loại bỏ toàn bộ các quyền capabilities. Độ tin cậy: 0.90
- Thực thi tiêu chuẩn bảo mật Pod mức hạn chế (restricted Pod Security Standard) trên các namespace chứa ứng dụng. Độ tin cậy: 0.80
- Khởi đầu mọi namespace bằng một NetworkPolicy mặc định chặn toàn bộ (default-deny) và chỉ mở đúng những luồng kết nối mà bạn thực sự cần. Độ tin cậy: 0.80
- Cấp cho mỗi workload một ServiceAccount riêng biệt và tắt tính năng tự động gắn kết token (automount) khi workload đó không bao giờ gọi tới API server. Độ tin cậy: 0.85
- Giữ các thông tin bí mật (secrets) nằm ngoài Git; đồng bộ chúng từ trình quản lý bí mật bằng External Secrets hoặc sử dụng Sealed Secrets. Độ tin cậy: 0.90
- Sử dụng một namespace cho mỗi nhóm (team) hoặc mỗi ứng dụng, đi kèm với ResourceQuota và LimitRange. Độ tin cậy: 0.80
- Áp dụng bộ nhãn tiêu chuẩn app.kubernetes.io cho mọi tài nguyên. Độ tin cậy: 0.75
- Xử lý tín hiệu SIGTERM và thêm một khoảng chờ ngắn (sleep) trong preStop để các yêu cầu đang xử lý dở (in-flight requests) hoàn tất trước khi tắt hẳn. Độ tin cậy: 0.85
- Mở rộng quy mô (scale) các dịch vụ không trạng thái (stateless) bằng HorizontalPodAutoscaler dựa trên mức sử dụng CPU hoặc chỉ số tốc độ yêu cầu thực tế. Độ tin cậy: 0.75
- Chạy cơ sở dữ liệu trên dịch vụ đám mây được quản lý (managed cloud service) thay vì dùng StatefulSets trừ khi có lý do thực sự thuyết phục. Độ tin cậy: 0.80
- Xác thực các tệp manifest trong quy trình CI bằng kubeconform và một công cụ kiểm tra chính sách như Kyverno hoặc OPA Gatekeeper. Độ tin cậy: 0.80
- Duy trì phiên bản của các cụm (clusters) không tụt hậu quá hai phiên bản phụ (minor versions) so với bản phát hành Kubernetes mới nhất và nâng cấp theo lịch trình định kỳ. Độ tin cậy: 0.75
- Phơi bày (expose) các dịch vụ HTTP thông qua một bộ điều khiển ingress dùng chung hoặc Gateway API controller, thay vì tạo một LoadBalancer riêng cho từng dịch vụ. Độ tin cậy: 0.75

---
name: vpc-subnet-cidr-planner
description: Quy hoạch và kiểm tra cách bố trí mạng con (subnet) IPv4 cho các mạng trên AWS, Azure, GCP hoặc tại chỗ (on-prem). Tính toán kích thước từng mạng con dựa trên số lượng máy trạm (host) cộng với mức tăng trưởng và các địa chỉ dành riêng của nhà cung cấp, cấp phát các khối CIDR được căn chỉnh theo thứ tự từ lớn nhất trước, đồng thời cảnh báo các mạng con bị chồng lấn, các dải VPC xung đột với VPC được kết nối ngang hàng (peered VPC), mạng VPN hoặc cầu nối docker0, các dải IP công cộng, giới hạn kích thước, khoảng dự phòng thấp và cách bố trí chỉ có một vùng (single-zone). Bao gồm công cụ quy hoạch viết bằng thư viện chuẩn Python kèm tùy chọn --self-test.
---

# Công cụ Quy hoạch CIDR Mạng con VPC

Bạn giúp các kỹ sư phân chia một mạng lớn thành các mạng con (subnet) vừa vặn với nhu cầu hiện tại, chừa đủ không gian để mở rộng và không bao giờ xung đột với bất kỳ mạng nào họ cần định tuyến tới trong tương lai. Bạn biến yêu cầu "chúng tôi cần các mạng con public, app và data ở hai vùng (zone)" thành các khối CIDR chính xác, giải thích rõ những con số tính toán và phát hiện sớm các điểm chồng lấn vốn rất vất vả để khắc phục một khi các tải công việc (workloads) đã đi vào vận hành.

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

- `scripts/cidr_plan.py` - tính toán kích thước và cấp phát các mạng con, liệt kê các dải địa chỉ host khả dụng cùng các khối còn trống, đồng thời báo cáo các phát hiện (chỉ dùng thư viện chuẩn Python 3, sử dụng mô-đun `ipaddress`)
- `references/cidr-math-and-provider-rules.md` - bảng kích thước tiền tố (prefix), quy tắc căn chỉnh (alignment), các địa chỉ dành riêng và giới hạn theo từng nhà cung cấp, các dải địa chỉ riêng (private ranges)
- `references/subnet-layout-playbook.md` - cách bố trí phân tầng (tiered layouts), chiến lược phân vùng (zone), tính toán kích thước mạng con cho pod Kubernetes, tránh chồng lấn với VPN và các mạng ngang hàng (peers), các phương án đánh số lại (renumbering)
- `templates/subnet-plan.md` - mẫu tài liệu quy hoạch mạng con dùng để rà soát hoặc đính kèm vào pull request
- `examples/shop-platform-vpc.json` - một mạng AWS /18 có các mạng con cũ (legacy), một VPC phân tích được kết nối ngang hàng (peered) và sáu mạng con mới trải trên hai vùng

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

### 1. Thu thập thông tin thực tế về mạng
Hỏi về nhà cung cấp dịch vụ, dải CIDR của VPC / VNet (hoặc dải địa chỉ họ dự định dùng), các mạng con hiện có, mọi mạng mà nó phải giao tiếp cùng (các VPC kết nối ngang hàng, mạng VPN, văn phòng tại chỗ on-prem, đường kết nối đối tác, các đám mây khác), và các mạng con họ cần tạo: mục đích sử dụng, vùng (zone), số lượng host hiện tại và mức tăng trưởng dự kiến. Đối với Kubernetes, hãy hỏi xem các pod có lấy địa chỉ trực tiếp từ VPC hay không (AWS VPC CNI, Azure CNI), vì khi đó chính số lượng pod chứ không phải số lượng node mới là yếu tố quyết định kích thước mạng con.

### 2. Chạy công cụ quy hoạch
```
python3 scripts/cidr_plan.py examples/shop-platform-vpc.json
python3 scripts/cidr_plan.py plan.json --json
python3 scripts/cidr_plan.py --self-test
```
Mã thoát (exit code) 1 nghĩa là có các phát hiện mức HIGH (chồng lấn địa chỉ, hết không gian trống), 2 nghĩa là dữ liệu đầu vào bị lỗi (các bit phần host bị bật, dùng IPv6, các dải VPC bị chồng lấn nhau).

### 3. Rà soát kết quả
Khắc phục các phát hiện mức HIGH trước: sự chồng lấn với mạng ngang hàng (peer) hoặc VPN sẽ không thể định tuyến được và thường đồng nghĩa với việc phải chọn một dải VPC mới ngay bây giờ khi chi phí thay đổi còn thấp. Sử dụng `references/subnet-layout-playbook.md` để điều chỉnh cách bố trí (các mạng con có kích thước bằng nhau ở mỗi vùng, chừa một khối dự phòng cho mỗi tầng, chừa chỗ cho vùng thứ ba) và dùng `references/cidr-math-and-provider-rules.md` để giải thích về kích thước. Chạy lại công cụ sau mỗi lần thay đổi.

### 4. Bàn giao kết quả
Điền vào `templates/subnet-plan.md` bảng quy hoạch, các khối còn trống, các phát hiện và quyết định. Cung cấp thêm các đoạn mã Terraform hoặc lệnh CLI cho các khối CIDR cuối cùng nếu được yêu cầu.

## Kết quả ví dụ
Đối với `examples/shop-platform-vpc.json` (AWS 10.20.0.0/18): các mạng con tầng app gồm 2,500 pod + 60% tăng trưởng được cấp các khối /20 (mỗi khối có 4,091 địa chỉ khả dụng) tại 10.20.16.0/20 và 10.20.32.0/20; các mạng con cho bộ cân bằng tải (load balancer) và tầng dữ liệu (data) được cấp các khối /25 (123 địa chỉ khả dụng). Các phát hiện: mức HIGH do mạng con cũ rds-b 10.20.1.128/25 bị chồng lấn với rds-a 10.20.1.0/24; mức HIGH do VPC phân tích được kết nối ngang hàng 10.20.48.0/20 nằm gọn bên trong dải VPC này nên việc định tuyến tới nó sẽ bị lỗi; mức LOW do chỉ còn trống 20% không gian địa chỉ.

## Quy tắc

- Không bao giờ đề xuất một dải địa chỉ bị chồng lấn với mạng ngang hàng (peer), VPN hoặc mạng tại chỗ (on-prem) đã biết; hãy hỏi danh sách đầy đủ nếu chưa chắc chắn.
- Quy hoạch có tính đến mức tăng trưởng và một vùng (zone) trong tương lai; việc thay đổi kích thước một mạng con tại chỗ thường là bất khả thi.
- Giữ các phép tính IPv4 tuyệt đối chính xác; hiển thị số lượng địa chỉ khả dụng sau khi đã trừ đi các địa chỉ dành riêng của nhà cung cấp.
- Không tự mình thay đổi các mạng đang hoạt động; hãy đưa ra bản quy hoạch và thứ tự thực hiện thay đổi để người dùng tự áp dụng.
FILE:references/cidr-math-and-provider-rules.md
# Toán học CIDR và Quy tắc của Nhà cung cấp

## Kích thước tiền tố (IPv4)
| Tiền tố (Prefix) | Tổng số địa chỉ | Khả dụng trên AWS / Azure (-5) | Khả dụng trên GCP (-4) | Khả dụng truyền thống (-2) |
|---|---|---|---|---|
| /16 | 65,536 | 65,531 | 65,532 | 65,534 |
| /18 | 16,384 | 16,379 | 16,380 | 16,382 |
| /19 | 8,192 | 8,187 | 8,188 | 8,190 |
| /20 | 4,096 | 4,091 | 4,092 | 4,094 |
| /21 | 2,048 | 2,043 | 2,044 | 2,046 |
| /22 | 1,024 | 1,019 | 1,020 | 1,022 |
| /23 | 512 | 507 | 508 | 510 |
| /24 | 256 | 251 | 252 | 254 |
| /25 | 128 | 123 | 124 | 126 |
| /26 | 64 | 59 | 60 | 62 |
| /27 | 32 | 27 | 28 | 30 |
| /28 | 16 | 11 | 12 | 14 |
Mỗi khi tiền tố tăng hoặc giảm 1 đơn vị thì kích thước khối địa chỉ sẽ giảm đi một nửa hoặc tăng gấp đôi. Số địa chỉ = 2^(32 - prefix).

## Quy tắc căn chỉnh (Alignment)
Một khối địa chỉ phải bắt đầu tại một bội số của chính kích thước khối đó: một khối /20 bắt đầu tại x.x.0.0, x.x.16.0, x.x.32.0, ...; cách viết 10.20.8.0/20 là không hợp lệ (do các bit phần host bị bật). Việc cấp phát các khối lớn nhất trước giúp giữ cho không gian địa chỉ không bị phân mảnh; nếu đặt các mạng con nhỏ vào trước, chúng có thể chặn mất mọi vị trí căn chỉnh hợp lệ dành cho một khối lớn.

## Các địa chỉ dành riêng trên mỗi mạng con
- **AWS:** bốn địa chỉ đầu tiên (địa chỉ mạng, bộ định tuyến VPC, DNS, dự phòng) và địa chỉ cuối cùng (broadcast) -> trừ 5 địa chỉ. CIDR của VPC từ /16 đến /28, các mạng con từ /16 đến /28. Mặc định tối đa 5 khối CIDR trên mỗi VPC (có thể thêm các CIDR phụ sau để mở rộng không gian).
- **Azure:** bốn địa chỉ đầu tiên (địa chỉ mạng, cổng gateway, 2 địa chỉ DNS) và địa chỉ cuối cùng -> trừ 5 địa chỉ. Mạng con nhỏ nhất đến /29. Một số dịch vụ yêu cầu các mạng con chuyên dụng riêng (GatewaySubnet từ /27 trở lên, AzureFirewallSubnet /26, AzureBastionSubnet /26).
- **GCP:** địa chỉ mạng, cổng gateway, địa chỉ áp chót và địa chỉ broadcast -> trừ 4 địa chỉ. Các mạng con có phạm vi theo khu vực (regional chứ không phải zonal), nhỏ nhất là /29; hỗ trợ các dải địa chỉ phụ (secondary ranges) cho các pod và service của GKE.
- **Truyền thống / tại chỗ (Classic / on-prem):** địa chỉ mạng và địa chỉ broadcast -> trừ 2 địa chỉ (các liên kết điểm-nối-điểm /31 là trường hợp đặc biệt).

## Các dải địa chỉ riêng và đặc biệt
- RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16.
- Không gian dùng chung cho Carrier-grade NAT 100.64.0.0/10 (RFC 6598): có thể dùng bên trong các đám mây, nhưng cần kiểm tra để đảm bảo nhà mạng ISP / VPN không sử dụng dải này.
- Nên tránh: 172.17.0.0/16 (cầu nối docker0 mặc định), 169.254.0.0/16 (link-local, dịch vụ metadata trên đám mây), 192.168.0.0/24 và 192.168.1.0/24 (bộ định tuyến gia đình hay dùng nên người dùng VPN sẽ bị xung đột), 10.0.0.0/16 (VPC mặc định trong nhiều công cụ nên các mạng kết nối ngang hàng thường bị đụng).
- Việc sử dụng các dải địa chỉ công cộng (public ranges) bên trong một VPC sẽ khiến các địa chỉ internet thực tế tương ứng không thể truy cập được từ bên trong VPC đó.

## Công thức tính nhanh
- Tiền tố nhỏ nhất cho N máy trạm (host) khả dụng với R địa chỉ dành riêng: 32 - ceil(log2(N + R)).
- Số lượng host tính cả mức tăng trưởng: ceil(hosts x (1 + growth)).
- Không gian trống sau khi quy hoạch = tổng địa chỉ VPC - (các mạng hiện có + mạng mới + các dải mạng ngang hàng bị chặn nằm bên trong VPC).
FILE:references/subnet-layout-playbook.md
# Sổ tay Bố trí Mạng con (Subnet Layout Playbook)

## Cách bố trí phân tầng trên mỗi vùng (zone)
| Tầng (Tier) | Thành phần chứa bên trong | Kích thước điển hình | Định tuyến (Route) |
|---|---|---|---|
| Public | bộ cân bằng tải (load balancers), cổng NAT (NAT gateways), máy chủ bastion | /24 đến /26 | cổng internet (internet gateway) |
| Private app | máy ảo (VMs), containers, các node và pod của Kubernetes | lớn nhất, /20 đến /22 | cổng NAT (NAT gateway) |
| Data | cơ sở dữ liệu, bộ nhớ đệm (caches), hàng đợi (queues) | /24 đến /26 | không có đường định tuyến ra internet |
| Spare (Dự phòng) | tầng tương lai hoặc vùng (zone) thứ ba | giữ lại một khối đã căn chỉnh | - |
Sử dụng cùng một kích thước cho mỗi tầng ở tất cả các vùng để khi chuyển đổi dự phòng (failover), vùng dự phòng có thể gánh toàn bộ tải.

## Chiến lược phân vùng (Zone strategy)
- Sử dụng ít nhất hai vùng (zones) cho bất kỳ hệ thống môi trường thực tế (production) nào; dùng ba vùng nếu khu vực (region) và ngân sách cho phép.
- Giữ chỗ trước các khối địa chỉ cho vùng thứ ba ngay từ bây giờ dù chưa dùng tới; việc này giúp cấu trúc bố trí luôn đối xứng.
- Các mạng con trên GCP có phạm vi theo khu vực (regional), vì vậy hãy quy hoạch theo từng khu vực thay vì theo từng vùng (zone).

## Tính toán kích thước cho Kubernetes
- Với AWS VPC CNI hoặc Azure CNI, mỗi pod sẽ lấy một địa chỉ IP từ VPC: hãy tính kích thước mạng con tầng app theo số lượng pod ở mức đỉnh (số node x số pod tối đa trên mỗi node), cộng thêm mức tăng đột biến trong quá trình cập nhật cuốn chiếu (rolling updates, thường là +25%) và khi thay thế node.
- Cơ chế ủy quyền tiền tố (Prefix delegation trên AWS) hoặc mạng phủ (overlay networking như Calico, Cilium, kubenet, Azure CNI Overlay) sẽ chuyển các pod sang một dải địa chỉ riêng biệt; khi đó chỉ cần tính kích thước mạng con theo số lượng node và giữ cho dải CIDR của pod không bị trùng với bất kỳ mạng ngang hàng nào.
- Giữ cho dải CIDR của service (ví dụ 172.20.0.0/16) cũng tách biệt hoàn toàn khỏi VPC và các mạng ngang hàng.

## Tránh chồng lấn địa chỉ
- Thu thập mọi mạng mà bạn sẽ cần định tuyến tới: các VPC và tài khoản khác, máy khách VPN, văn phòng, đối tác, các đám mây khác và cả những dải mạng đang được sử dụng bởi các công ty được mua lại/sáp nhập.
- Duy trì một bảng quy hoạch IP tập trung (bảng tính hoặc hệ thống IPAM) và cấp cho mỗi môi trường một khối riêng biệt, ví dụ: 10.20.0.0/16 cho prod, 10.21.0.0/16 cho staging, 10.22.0.0/16 cho dev.
- Không chọn các dải 10.0.0.0/16, 172.17.0.0/16 hoặc từ 192.168.0.0/24 đến 192.168.1.0/24 cho bất kỳ hệ thống nào mà người dùng VPN sẽ kết nối vào.

## Khi đã xảy ra chồng lấn
1. Ưu tiên đánh số lại (renumbering) phía mạng nhỏ hơn hoặc mới hơn ngay lập tức (tạo VPC mới hoặc thêm một dải CIDR phụ, di chuyển hệ thống sang, rồi xóa mạng cũ).
2. Nếu không thể đánh số lại, hãy sử dụng NAT (private NAT gateway, hoặc NAT trên thiết bị VPN) và chỉ định tuyến các dải địa chỉ đã được biên dịch (translated ranges).
3. Các mạng con chồng lấn bên trong cùng một VPC không thể tạo được trên AWS / Azure / GCP; nếu thấy xuất hiện trong tài liệu thì thường là do lỗi gõ nhầm, vì vậy hãy kiểm tra lại các giá trị thực tế.

## Danh sách kiểm tra rà soát (Review checklist)
- [ ] Dải VPC là địa chỉ riêng (private) và duy nhất trên tất cả các mạng ngang hàng (peers) cùng mạng VPN
- [ ] Mọi mạng con đều được căn chỉnh đúng, nằm trong VPC và không bị chồng lấn nhau
- [ ] Kích thước đã tính gộp cả các địa chỉ dành riêng và mức tăng trưởng dự kiến
- [ ] Các tầng cùng loại có kích thước bằng nhau ở mỗi vùng; có giữ lại khối dự phòng
- [ ] Còn trống ít nhất 25% không gian địa chỉ của VPC
FILE:templates/subnet-plan.md
# Bản Quy hoạch Mạng con - <tên mạng>

**Nhà cung cấp / khu vực:** <aws eu-west-1>  **VPC CIDR:** <10.x.0.0/16>  **Đơn vị sở hữu:** <nhóm>  **Ngày:** <ngày>
**Các mạng ngang hàng (Peers) / VPN đã kiểm tra:** <danh sách các dải địa chỉ>

## Các mạng con (Subnets)
| Mạng con | Tầng (Tier) | Vùng (Zone) | Số host hiện tại | Mức tăng trưởng | CIDR | Số IP khả dụng | Bảng định tuyến (Route table) |
|---|---|---|---|---|---|---|---|
| | | | | | | | |

## Các mạng con hiện có được giữ lại
| Tên | CIDR | Ghi chú |
|---|---|---|
| | | |

## Không gian trống
- Đã sử dụng hoặc bị chặn: <n> trên tổng số <total> (còn trống <x>%)
- Các khối dự phòng được giữ chỗ cho: <vùng thứ ba / tầng tương lai>

## Các phát hiện và quyết định
| Mức độ nghiêm trọng | Phát hiện | Quyết định |
|---|---|---|
| | | |

## Thứ tự triển khai (Rollout order)
1. <tạo CIDR phụ / tạo VPC mới>
2. <tạo các mạng con và bảng định tuyến>
3. <di chuyển các tải công việc (workloads), xóa các mạng con cũ>
FILE:examples/shop-platform-vpc.json
{
  "name": "shop platform, eu-west-1 production VPC",
  "provider": "aws",
  "vpc_cidrs": ["10.20.0.0/18"],
  "existing": [
    {"name": "legacy bastion", "cidr": "10.20.0.0/26"},
    {"name": "legacy rds-a", "cidr": "10.20.1.0/24"},
    {"name": "legacy rds-b", "cidr": "10.20.1.128/25"}
  ],
  "peers": [
    {"name": "office VPN (Istanbul)", "cidr": "192.168.10.0/24"},
    {"name": "analytics VPC (peered)", "cidr": "10.20.48.0/20"}
  ],
  "requests": [
    {"name": "public-a (load balancers)", "hosts": 40, "zone": "eu-west-1a", "growth": 0.5},
    {"name": "public-b (load balancers)", "hosts": 40, "zone": "eu-west-1b", "growth": 0.5},
    {"name": "app-a (EKS pods)", "hosts": 2500, "zone": "eu-west-1a", "growth": 0.6},
    {"name": "app-b (EKS pods)", "hosts": 2500, "zone": "eu-west-1b", "growth": 0.6},
    {"name": "data-a (databases, cache)", "hosts": 60, "zone": "eu-west-1a"},
    {"name": "data-b (databases, cache)", "hosts": 60, "zone": "eu-west-1b"}
  ]
}
FILE:scripts/cidr_plan.py
#!/usr/bin/env python3
"""VPC subnet CIDR planner and checker (Python 3 standard library only).

Input: a network plan JSON file:
  {"name": "prod-eu", "provider": "aws", "vpc_cidrs": ["10.40.0.0/16"],
   "existing": [{"name": "legacy-db", "cidr": "10.40.8.0/24"}],
   "peers": [{"name": "office vpn", "cidr": "192.168.0.0/22"}],
   "requests": [{"name": "app-a", "hosts": 900, "zone": "eu-west-1a", "growth": 0.5}]}
  provider: aws | azure | gcp | generic. Reserved addresses per subnet: aws 5, azure 5,
  gcp 4, generic 2 (network + broadcast). Subnet size limits: aws /16../28,
  azure /8../29, gcp /8../29, generic /8../30.
  requests: hosts needed now; growth = extra fraction to reserve (default 0.3);
  optional "prefix" forces a size. Allocation is largest-first, aligned, lowest free address,
  never overlapping existing subnets or peer networks that sit inside the VPC.

Checks (severity):
  HIGH   OVERLAP_EXISTING   two existing subnets overlap
  HIGH   OUTSIDE_VPC        existing subnet not inside any VPC CIDR
  HIGH   PEER_OVERLAP       VPC CIDR overlaps a peered / VPN / on-prem network (routing breaks)
  HIGH   NO_SPACE           a request does not fit in the remaining space
  MEDIUM DOCKER_DEFAULT     VPC overlaps 172.17.0.0/16 (default docker0 bridge)
  MEDIUM PUBLIC_RANGE       VPC CIDR is not private (RFC 1918 / 100.64.0.0/10)
  MEDIUM PREFIX_LIMIT       requested or VPC prefix outside the provider limits
  LOW    LOW_HEADROOM       less than 25% of the VPC left free after the plan
  LOW    SINGLE_ZONE        all requests in one zone (no zone redundancy)
Usage:
  python3 cidr_plan.py plan.json
  python3 cidr_plan.py plan.json --json
  python3 cidr_plan.py --self-test
Exit code: 0 no HIGH findings, 1 HIGH findings, 2 bad input.
"""
import argparse
import ipaddress as ip
import json
import math
import sys

RESERVED = {"aws": 5, "azure": 5, "gcp": 4, "generic": 2}
HEAD_RESERVED = {"aws": 4, "azure": 4, "gcp": 2, "generic": 1}  # rest are at the end of the block
LIMITS = {"aws": (16, 28), "azure": (8, 29), "gcp": (8, 29), "generic": (8, 30)}
PRIVATE = [ip.ip_network(c) for c in ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10")]
DOCKER = ip.ip_network("172.17.0.0/16")


class PlanError(ValueError):
    pass


def net(cidr, what="cidr"):
    try:
        n = ip.ip_network(str(cidr).strip(), strict=True)
    except ValueError as e:
        raise PlanError(f"bad {what} {cidr!r}: {e}")
    if n.version != 4:
        raise PlanError(f"only IPv4 is supported: {cidr!r}")
    return n


def usable(prefix, provider):
    return max(0, 2 ** (32 - prefix) - RESERVED[provider])


def prefix_for(hosts, provider, growth):
    need = math.ceil(hosts * (1 + growth))
    lo, hi = LIMITS[provider]
    for p in range(hi, lo - 1, -1):
        if usable(p, provider) >= need:
            return p
    return None


def find_slot(vpcs, taken, prefix):
    for v in vpcs:
        if prefix < v.prefixlen:
            continue
        for cand in v.subnets(new_prefix=prefix):
            if not any(cand.overlaps(t) for t in taken):
                return cand
    return None


def plan(cfg):
    provider = str(cfg.get("provider", "generic")).lower()
    if provider not in RESERVED:
        raise PlanError(f"unknown provider {provider!r} (aws, azure, gcp, generic)")
    vpcs = [net(c, "vpc_cidr") for c in cfg.get("vpc_cidrs") or []]
    if not vpcs:
        raise PlanError("vpc_cidrs is empty")
    lo, hi = LIMITS[provider]
    findings = []

    def f(sev, code, where, msg):
        findings.append({"severity": sev, "code": code, "where": where, "message": msg})

    for v in vpcs:
        if not any(v.subnet_of(p) for p in PRIVATE):
            f("MEDIUM", "PUBLIC_RANGE", str(v), "not an RFC 1918 or 100.64.0.0/10 range; it may clash with real internet addresses")
        if v.overlaps(DOCKER):
            f("MEDIUM", "DOCKER_DEFAULT", str(v), "overlaps 172.17.0.0/16, the default docker0 bridge; containers on hosts in this VPC may lose routes")
        if provider == "aws" and not (16 <= v.prefixlen <= 28):
            f("MEDIUM", "PREFIX_LIMIT", str(v), "AWS VPC CIDR blocks must be /16 to /28")
    for i, a in enumerate(vpcs):
        for b in vpcs[i + 1:]:
            if a.overlaps(b):
                raise PlanError(f"vpc_cidrs overlap each other: {a} and {b}")

    existing = []
    for e in cfg.get("existing") or []:
        n = net(e.get("cidr"), "existing cidr")
        name = e.get("name") or str(n)
        if not any(n.subnet_of(v) for v in vpcs):
            f("HIGH", "OUTSIDE_VPC", name, f"{n} is not inside {', '.join(map(str, vpcs))}")
        for other_name, o in existing:
            if n.overlaps(o):
                f("HIGH", "OVERLAP_EXISTING", name, f"{n} overlaps {other_name} {o}")
        existing.append((name, n))

    taken = [n for _, n in existing]
    for p in cfg.get("peers") or []:
        n = net(p.get("cidr"), "peer cidr")
        name = p.get("name") or str(n)
        for v in vpcs:
            if v.overlaps(n):
                f("HIGH", "PEER_OVERLAP", name, f"{n} overlaps VPC {v}; traffic to the overlapping range cannot be routed both ways (renumber one side or use NAT)")
                taken.append(n)

    reqs = []
    for r in cfg.get("requests") or []:
        name = r.get("name") or "subnet"
        hosts = r.get("hosts", 0)
        if not isinstance(hosts, int) or isinstance(hosts, bool) or hosts < 1:
            raise PlanError(f"request {name!r}: hosts must be a positive integer")
        growth = r.get("growth", 0.3)
        if not isinstance(growth, (int, float)) or growth < 0:
            raise PlanError(f"request {name!r}: growth must be >= 0")
        if "prefix" in r:
            pfx = r["prefix"]
            if not isinstance(pfx, int) or not 8 <= pfx <= 30:
                raise PlanError(f"request {name!r}: prefix must be an integer 8..30")
            if not lo <= pfx <= hi:
                f("MEDIUM", "PREFIX_LIMIT", name, f"/{pfx} is outside {provider} subnet limits /{lo}../{hi}")
        else:
            pfx = prefix_for(hosts, provider, growth)
        reqs.append({"name": name, "hosts": hosts, "growth": growth, "zone": r.get("zone", ""), "prefix": pfx})

    allocs = []
    order = sorted(range(len(reqs)), key=lambda i: (reqs[i]["prefix"] if reqs[i]["prefix"] is not None else -1, i))
    for i in order:
        r = reqs[i]
        slot = find_slot(vpcs, taken, r["prefix"]) if r["prefix"] is not None else None
        if slot is None:
            f("HIGH", "NO_SPACE", r["name"], f"needs {r['hosts']} hosts (+{round(r['growth'] * 100)}% growth) and no free aligned block is left")
            allocs.append(dict(r, cidr=None, usable=0))
            continue
        taken.append(slot)
        u = usable(slot.prefixlen, provider)
        tail = RESERVED[provider] - HEAD_RESERVED[provider]
        allocs.append(dict(r, cidr=str(slot), usable=u,
                           first=str(slot[HEAD_RESERVED[provider]]) if u else "-",
                           last=str(slot[-1 - tail]) if u else "-"))
        if u < r["hosts"]:
            f("HIGH", "NO_SPACE", r["name"], f"/{slot.prefixlen} gives only {u} usable addresses for {r['hosts']} hosts")
    allocs.sort(key=lambda a: (a["cidr"] is None, ip.ip_network(a["cidr"]) if a["cidr"] else 0))

    total = sum(v.num_addresses for v in vpcs)
    used = 0
    inside = [t for t in taken if any(t.subnet_of(v) for v in vpcs)]
    for t in ip.collapse_addresses(inside):
        used += t.num_addresses
    free = total - used
    free_blocks = []
    for v in vpcs:
        rest = [v]
        for t in ip.collapse_addresses([x for x in inside if x.subnet_of(v)]):
            nxt = []
            for b in rest:
                if t.subnet_of(b):
                    nxt.extend(b.address_exclude(t))
                elif not b.subnet_of(t):
                    nxt.append(b)
            rest = nxt
        free_blocks.extend(sorted(rest))
    if total and free / total < 0.25:
        f("LOW", "LOW_HEADROOM", "plan", f"only {free / total:.0%} of the VPC address space is left free")
    zones = {r["zone"] for r in reqs if r["zone"]}
    if len(reqs) > 1 and len(zones) == 1:
        f("LOW", "SINGLE_ZONE", "plan", f"all requests are in {zones.pop()}; spread subnets over at least two zones")
    rank = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
    findings.sort(key=lambda x: rank[x["severity"]])
    return {"name": cfg.get("name", "network plan"), "provider": provider, "vpcs": [str(v) for v in vpcs],
            "existing": [{"name": n, "cidr": str(c)} for n, c in existing],
            "allocations": allocs, "total": total, "used": used, "free": free,
            "free_blocks": [str(b) for b in free_blocks], "findings": findings}


def report(res):
    out = [f"# Subnet plan: {res['name']}", "",
           f"Provider: {res['provider']} (reserves {RESERVED[res['provider']]} addresses per subnet)  VPC: {', '.join(res['vpcs'])}", "",
           "| Subnet | Zone | Hosts now | Growth | CIDR | Usable | First host | Last host |", "|---|---|---|---|---|---|---|---|"]
    for a in res["allocations"]:
        out.append(f"| {a['name']} | {a['zone'] or '-'} | {a['hosts']} | {round(a['growth'] * 100)}% | {a['cidr'] or 'NOT PLACED'} | "
                   f"{a['usable']} | {a.get('first', '-')} | {a.get('last', '-')} |")
    if res["existing"]:
        out += ["", "Existing subnets kept: " + ", ".join(f"{e['name']} {e['cidr']}" for e in res["existing"])]
    pct = res["free"] / res["total"] if res["total"] else 0
    out += ["", f"Address space: {res['used']} of {res['total']} used or blocked, {res['free']} free ({pct:.0%})",
            "Largest free blocks: " + (", ".join(sorted(res["free_blocks"], key=lambda c: ip.ip_network(c).prefixlen)[:6]) or "none"),
            "", "## Findings"]
    if not res["findings"]:
        out.append("- none")
    for x in res["findings"]:
        out.append(f"- **{x['severity']} {x['code']}** ({x['where']}): {x['message']}")
    return "\n".join(out) + "\n"


def self_test():
    cases = []

    def ok(name, cond):
        cases.append(bool(cond))
        print(("PASS " if cond else "FAIL ") + name)

    ok("aws /24 usable 251", usable(24, "aws") == 251)
    ok("generic /24 usable 254", usable(24, "generic") == 254)
    ok("gcp /29 usable 4", usable(29, "gcp") == 4)
    ok("900 hosts +50% on aws -> /21", prefix_for(900, "aws", 0.5) == 21)
    ok("250 hosts no growth aws -> /24", prefix_for(250, "aws", 0) == 24)
    ok("252 hosts no growth aws -> /23", prefix_for(252, "aws", 0) == 23)
    ok("too big for aws -> None", prefix_for(70000, "aws", 0) is None)
    base = {"provider": "aws", "vpc_cidrs": ["10.0.0.0/16"]}
    r = plan(dict(base, requests=[{"name": "a", "hosts": 200, "zone": "z1"}, {"name": "b", "hosts": 1000, "zone": "z2"}]))
    cid = {a["name"]: a["cidr"] for a in r["allocations"]}
    ok("largest first gets lowest block", cid == {"b": "10.0.0.0/21", "a": "10.0.8.0/23"})
    ok("clean plan has no findings", r["findings"] == [])
    aa = [a for a in r["allocations"] if a["name"] == "a"][0]
    ok("first/last host skip aws reserved", (aa["first"], aa["last"]) == ("10.0.8.4", "10.0.9.254"))
    g = plan({"provider": "gcp", "vpc_cidrs": ["10.0.0.0/16"], "requests": [{"name": "a", "hosts": 100, "growth": 0}]})["allocations"][0]
    ok("gcp reserves 2 head + 2 tail", (g["cidr"], g["first"], g["last"]) == ("10.0.0.0/25", "10.0.0.2", "10.0.0.125"))
    r = plan(dict(base, existing=[{"name": "old", "cidr": "10.0.0.0/22"}], requests=[{"name": "a", "hosts": 1000}]))
    ok("allocation avoids existing", r["allocations"][0]["cidr"] == "10.0.8.0/21")
    r = plan(dict(base, existing=[{"name": "x", "cidr": "10.0.0.0/24"}, {"name": "y", "cidr": "10.0.0.128/25"}]))
    ok("overlap existing flagged", any(x["code"] == "OVERLAP_EXISTING" for x in r["findings"]))
    r = plan(dict(base, existing=[{"name": "x", "cidr": "10.1.0.0/24"}]))
    ok("outside vpc flagged", any(x["code"] == "OUTSIDE_VPC" for x in r["findings"]))
    r = plan(dict(base, peers=[{"name": "vpn", "cidr": "10.0.4.0/22"}], requests=[{"name": "a", "hosts": 900, "growth": 0}]))
    ok("peer overlap flagged", any(x["code"] == "PEER_OVERLAP" for x in r["findings"]))
    ok("allocation avoids peer range", r["allocations"][0]["cidr"] == "10.0.0.0/22")
    r = plan({"provider": "aws", "vpc_cidrs": ["10.0.0.0/24"], "requests": [{"name": "a", "hosts": 200}]})
    ok("no space flagged", any(x["code"] == "NO_SPACE" for x in r["findings"]))
    r = plan({"provider": "generic", "vpc_cidrs": ["172.16.0.0/12"]})
    ok("docker default flagged", any(x["code"] == "DOCKER_DEFAULT" for x in r["findings"]))
    r = plan({"provider": "generic", "vpc_cidrs": ["8.8.0.0/16"]})
    ok("public range flagged", any(x["code"] == "PUBLIC_RANGE" for x in r["findings"]))
    r = plan({"provider": "aws", "vpc_cidrs": ["10.0.0.0/8"]})
    ok("aws vpc /8 flagged", any(x["code"] == "PREFIX_LIMIT" for x in r["findings"]))
    r = plan({"provider": "aws", "vpc_cidrs": ["10.0.0.0/22"], "requests": [{"name": "a", "hosts": 400, "zone": "z1"}, {"name": "b", "hosts": 300, "zone": "z1"}]})
    ok("low headroom flagged", any(x["code"] == "LOW_HEADROOM" for x in r["findings"]))
    ok("single zone flagged", any(x["code"] == "SINGLE_ZONE" for x in r["findings"]))
    r = plan(dict(base, requests=[{"name": "a", "hosts": 10, "prefix": 30}]))
    ok("forced /30 on aws flagged", any(x["code"] == "PREFIX_LIMIT" for x in r["findings"]))
    r = plan(dict(base, requests=[{"name": "a", "hosts": 1000}]))
    ok("free blocks cover rest", sum(ip.ip_network(b).num_addresses for b in r["free_blocks"]) == 65536 - 2048)
    for bad, label in ((dict(base, vpc_cidrs=[]), "empty vpc"), (dict(base, vpc_cidrs=["10.0.0.1/16"]), "host bits set"),
                       (dict(base, provider="oracle"), "unknown provider"), (dict(base, requests=[{"hosts": 0}]), "zero hosts"),
                       (dict(base, vpc_cidrs=["10.0.0.0/16", "10.0.128.0/17"]), "overlapping vpcs"),
                       (dict(base, vpc_cidrs=["fd00::/48"]), "ipv6")):
        try:
            plan(bad)
            ok(label + " rejected", False)
        except PlanError:
            ok(label + " rejected", True)
    print(f"{sum(cases)}/{len(cases)} passed")
    return 0 if all(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Plan and check VPC subnet CIDR blocks.")
    ap.add_argument("file", nargs="?", help="network plan JSON")
    ap.add_argument("--json", action="store_true", help="print machine-readable JSON")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        ap.error("give a plan JSON file or --self-test")
    try:
        cfg = json.load(open(a.file, encoding="utf-8"))
        res = plan(cfg)
    except (OSError, json.JSONDecodeError, PlanError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(res, indent=2) if a.json else report(res), end="" if not a.json else "\n")
    return 1 if any(x["severity"] == "HIGH" for x in res["findings"]) else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: kubernetes-resource-requests-rightsizer
description: Tối ưu hóa đúng định mức (rightsize) các thông số requests và limits cho CPU và bộ nhớ trong Kubernetes dựa trên mức sử dụng thực tế (p50, p95 và max trên từng container). Đề xuất mức requests tại ngưỡng p95 cộng thêm khoảng dự phòng (headroom), giới hạn bộ nhớ (memory limits) cao hơn mức đỉnh và loại bỏ giới hạn CPU (CPU limits), đồng thời ước tính số lõi (cores), dung lượng GiB và chi phí tiết kiệm được. Cảnh báo các lỗi OOM kill, mức dùng bộ nhớ vượt quá request, hiện tượng bóp băng thông CPU (CPU throttling), thiếu thông số requests hoặc memory limits, cấp phát dư thừa (overprovisioning) và khoảng thời gian thu thập dữ liệu quá ngắn. Bao gồm một công cụ tính toán bằng thư viện chuẩn Python có hỗ trợ cờ --self-test.
---

# Công cụ Tối ưu hóa Định mức Tài nguyên Kubernetes (Rightsizer)

Bạn giúp các kỹ sư nền tảng (platform engineers), kỹ sư SRE và nhà phát triển thiết lập thông số requests và limits cho các container Kubernetes dựa trên bằng chứng số liệu thực tế thay vì phỏng đoán. Từ các phân vị mức sử dụng (usage percentiles) được xuất ra từ Prometheus, Datadog hoặc trình đề xuất VPA, bạn đề xuất thông số requests và limits mới cho từng container, giải thích các rủi ro nguy hiểm trước tiên (lỗi OOM kill, nghẽn CPU do throttling, nguy cơ bị trục xuất pod - eviction), ước tính lượng tài nguyên mà cụm (cluster) tiết kiệm được, và lập kế hoạch triển khai an toàn.

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

- `scripts/rightsize.py` - đọc tệp CSV chứa các thiết lập hiện tại và phân vị mức sử dụng của từng container, sau đó in ra thông số requests và limits được khuyến nghị, các phát hiện rủi ro và lượng tài nguyên requests được giải phóng (chỉ dùng thư viện chuẩn của Python 3)
- `references/sizing-method.md` - vai trò của requests và limits, quy tắc tính toán định mức, các chỉ số cần thu thập (kèm câu truy vấn PromQL), và cách đọc số liệu của các container đang bị bóp CPU (throttled) hoặc bị OOM kill
- `references/rollout-and-guardrails.md` - thứ tự áp dụng thay đổi, quy trình triển khai (rollout) và hoàn tác (rollback) an toàn, LimitRange, ResourceQuota, VPA, cảnh báo (alerts), và những trường hợp không nên cắt giảm tài nguyên
- `templates/rightsizing-plan.md` - mẫu kế hoạch tối ưu hóa định mức tài nguyên để chia sẻ với nhóm hoặc đính kèm vào phiếu yêu cầu thay đổi (change ticket)
- `examples/shop-cluster-usage.csv` - sáu container của một hệ thống cửa hàng trực tuyến: một API được cấp phát quá dư thừa, container sidecar đi kèm của nó, một dịch vụ tìm kiếm vừa bị OOM kill vừa bị bóp CPU, một worker không đặt giới hạn bộ nhớ, Redis và một trình đẩy log (log shipper) không khai báo requests

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

### 1. Thu thập số liệu sử dụng
Hãy yêu cầu dữ liệu thống kê theo từng container trong ít nhất 7 ngày (tốt nhất là 14-28 ngày): số lượng bản sao (replicas), thông số requests và limits hiện tại, phân vị p50/p95/max của CPU tính bằng millicores, phân vị p50/p95/max của bộ nhớ làm việc (memory working set) tính bằng MiB, tỷ lệ phần trăm bị bóp CPU (throttled percentage) và số lần bị OOM kill. Tệp `references/sizing-method.md` có sẵn câu truy vấn PromQL cho từng chỉ số này. Hãy hỏi thêm về nhiệm vụ của từng workload, đặc điểm biến thiên lưu lượng truy cập (đỉnh điểm hàng tuần, đợt khuyến mãi, tác vụ chạy theo lô batch jobs) và liệu có đang dùng HPA để tự động co giãn cho nó hay không.

### 2. Chạy công cụ tối ưu hóa định mức
```
python3 scripts/rightsize.py examples/shop-cluster-usage.csv --core-month 24 --gib-month 3.2
python3 scripts/rightsize.py usage.csv --headroom 25 --keep-cpu-limits --json
python3 scripts/rightsize.py --self-test
```
Thông số đơn giá là tùy chọn và được tính trên mỗi lõi (core) hoặc mỗi GiB được yêu cầu (requested) mỗi tháng. Mã thoát (exit code) bằng 1 nghĩa là có phát hiện rủi ro mức CRITICAL hoặc HIGH, bằng 2 nghĩa là dữ liệu đầu vào không hợp lệ.

### 3. Giải thích và lập kế hoạch
Bắt đầu với các container có mức cảnh báo CRITICAL và HIGH: nêu rõ vấn đề gì đang xảy ra hiện nay, bằng chứng số liệu cụ thể và thay đổi cần áp dụng. Đối với các container đang bị bóp CPU hoặc bị OOM kill, hãy lưu ý rằng các con số sử dụng hiện tại đã bị chạm trần giới hạn và cần lên kế hoạch đo đạc lại lần thứ hai sau khi khắc phục. Tiếp theo, liệt kê các khoản tiết kiệm lớn nhất (số lượng replicas sẽ nhân bội mức tiết kiệm này lên). Kiểm tra các trường hợp ngoại lệ trong `references/rollout-and-guardrails.md` mà việc cắt giảm tài nguyên là không an toàn, đồng thời nhắc nhở việc tinh chỉnh lại ngưỡng HPA khi thay đổi thông số requests.

### 4. Bàn giao kết quả
Điền vào mẫu `templates/rightsizing-plan.md` với bảng tổng hợp, bản vá YAML (YAML patch) cho từng workload, thứ tự triển khai, các chỉ số cần theo dõi và ngày hẹn đo đạc lại.

## Ví dụ kết quả
Đối với tệp `examples/shop-cluster-usage.csv`: container shop/catalog-search/app ở mức CRITICAL (bị OOM kill 3 lần tại ngưỡng giới hạn 1536Mi, mức bộ nhớ p95 là 1180Mi vượt quá mức request 1024Mi, bị bóp CPU 31% tại ngưỡng giới hạn 500m) và được đề xuất mức requests mới là 570m / 1360Mi, giới hạn bộ nhớ 1872Mi và gỡ bỏ hoàn toàn giới hạn CPU; ops/log-shipper hoàn toàn không có thông số requests nào (mức HIGH, chạy 8 replicas); shop/image-resizer cần bổ sung giới hạn bộ nhớ và tăng thêm bộ nhớ; shop/checkout-api/app giảm từ 1000m / 2048Mi xuống còn 485m / 912Mi trên 6 replicas. Tổng cộng giải phóng được 1.76 cores và 4.06 GiB tài nguyên requests, tương đương tiết kiệm khoảng 55 mỗi tháng nếu tính theo đơn giá 24 trên mỗi core và 3.2 trên mỗi GiB.

## Quy tắc

- Luôn khắc phục các rủi ro về độ tin cậy trước khi tối ưu tiết kiệm chi phí, và tuyệt đối không bao giờ khuyến nghị gỡ bỏ giới hạn bộ nhớ (memory limit).
- Luôn nêu rõ mỗi con số đề xuất được tính từ phân vị nào, khoảng thời gian dữ liệu bao lâu và tỷ lệ dự phòng (headroom) là bao nhiêu, đồng thời lưu ý rằng các đợt tăng vọt hiếm gặp nằm ngoài khoảng thời gian thu thập dữ liệu sẽ chưa được tính tới.
- Coi mức sử dụng của các container đang bị bóp CPU (throttled) hoặc bị OOM kill chỉ là mức sàn tối thiểu (floor), chứ chưa phải nhu cầu thực tế của chúng.
- Cung cấp các thay đổi dưới dạng bản vá tệp manifest hoặc Helm values để đội ngũ kỹ thuật xem xét; không tự ý chạy các lệnh `kubectl` trực tiếp lên cụm đang hoạt động.
- Báo cáo mức tiết kiệm dưới dạng "tài nguyên requests được giải phóng" cho tới khi các máy chủ nút (nodes) thực sự được thu hồi giảm bớt.
FILE:references/sizing-method.md
# Phương pháp Tính toán Định mức (Sizing Method)

## Vai trò của requests và limits
- **CPU request:** lượng tài nguyên mà bộ lập lịch (scheduler) đặt chỗ trước trên một node và là tỷ trọng chia sẻ CPU của container đó khi node rơi vào trạng thái bận. Đặt quá thấp: pod bị xếp vào các node chật chội và chạy chậm đi khi tải cao. Đặt quá cao: các node trông có vẻ đã đầy trên sổ sách trong khi thực tế lại đang nhàn rỗi, khiến bạn phải trả tiền cho những lõi CPU bỏ không.
- **CPU limit:** mức trần cứng được thực thi bởi hạn ngạch CFS (CFS quota) theo từng chu kỳ 100 ms. Một container chạm tới ngưỡng này sẽ bị bóp băng thông (throttled), ngay cả khi node đó đang dư thừa CPU nhàn rỗi. Các dịch vụ nhạy cảm với độ trễ (API, proxy, ứng dụng JVM và chương trình Go sử dụng nhiều luồng) sẽ chịu ảnh hưởng nặng nề nhất.
- **Memory request:** lượng bộ nhớ mà bộ lập lịch đặt chỗ trước. Các pod sử dụng nhiều bộ nhớ hơn mức request của chúng sẽ là đối tượng đầu tiên bị trục xuất (evicted) khi một node cạn kiệt bộ nhớ.
- **Memory limit:** mức trần cứng; vượt quá ngưỡng này đồng nghĩa với việc bị OOM kill ngay lập tức (mã thoát 137, lý do `OOMKilled`). Bộ nhớ không thể bị làm chậm (throttled) như CPU.
- **Các hạng QoS (QoS classes):** Guaranteed (requests = limits cho mọi container trong pod), Burstable (có thiết lập một số thông số requests), BestEffort (không thiết lập gì cả, sẽ bị trục xuất đầu tiên khi thiếu tài nguyên).

## Các quy tắc được sử dụng bởi `scripts/rightsize.py`
| Thông số | Quy tắc tính | Lý do |
|---|---|---|
| CPU request | p95 x (1 + headroom), làm tròn lên theo bậc 5m, tối thiểu 10m | đáp ứng tốt các giai đoạn bận rộn thông thường; phần nhu cầu đột biến còn lại sẽ tận dụng nguồn CPU nhàn rỗi dùng chung |
| CPU limit | gỡ bỏ (hoặc nếu dùng cờ `--keep-cpu-limits`: max(max x 1.2, 2 x request)) | giới hạn CPU gây nghẽn các đợt xử lý đột biến ngay cả trên các node đang rảnh |
| Memory request | p95 x (1 + headroom), làm tròn lên theo bậc 16Mi, tối thiểu 32Mi | giữ cho pod nằm ngoài danh sách ưu tiên bị trục xuất (eviction) |
| Memory limit | max(max x 1.25, request), làm tròn lên theo bậc 16Mi | tạo khoảng trống cho các đỉnh tải; không bao giờ được gỡ bỏ vì một lỗi rò rỉ bộ nhớ (memory leak) không được phép đánh sập cả node |

Tỷ lệ dự phòng (headroom) mặc định là 15%. Hãy nâng lên mức 25-30% đối với các lưu lượng có tính chất tăng vọt đột ngột (spiky traffic), các tác vụ chạy theo lô (batch jobs) hoặc khi khoảng thời gian thu thập dữ liệu quá ngắn.

## Các chỉ số cần thu thập
Trên từng container, trong khoảng thời gian ít nhất 7 ngày (tốt nhất là 14-28 ngày để bắt được các đỉnh tải hàng tuần và cuối tháng):
- CPU tính bằng millicores: giá trị p50, p95 và max của `rate(container_cpu_usage_seconds_total[5m]) * 1000`
- Bộ nhớ tính bằng MiB: giá trị p50, p95 và max của `container_memory_working_set_bytes / 2^20` (working set chính là chỉ số mà trình OOM killer và cơ chế trục xuất eviction theo dõi, chứ không phải RSS hay cache)
- Tỷ lệ bóp CPU (Throttling): `container_cpu_cfs_throttled_periods_total / container_cpu_cfs_periods_total * 100`
- Số lần OOM kill: `kube_pod_container_status_last_terminated_reason{reason="OOMKilled"}` hoặc số lần khởi động lại (restarts) với mã thoát 137
- Thiết lập hiện tại: dùng lệnh `kubectl get deploy -o jsonpath` hoặc chỉ số `kube_pod_container_resource_requests` / `_limits`

## Cách đọc kết quả
- **Các container bị bóp CPU (Throttled containers)** sẽ báo cáo mức sử dụng bị chặn đứng tại ngưỡng limit, do đó chỉ số p95 thu được thấp hơn nhu cầu thực tế. Hãy nâng cao hoặc gỡ bỏ giới hạn CPU trước, đo đạc lại trong vài ngày, rồi mới tính toán định mức chuẩn.
- **Các lỗi OOM kill** có nghĩa là mức đỉnh thực sự vẫn chưa xác định được (vì container đã bị giết ngay khi chạm ngưỡng limit). Hãy tăng giới hạn bộ nhớ lên thêm 50% hoặc nhiều hơn, tìm nguyên nhân rò rỉ bộ nhớ hoặc truy vấn nặng gây tốn RAM, sau đó đo đạc lại.
- **Ứng dụng JVM, Node.js và Go** đọc kích thước vùng nhớ heap từ cấu hình khởi chạy: hãy thay đổi các cờ `-Xmx`, `--max-old-space-size` hoặc `GOMEMLIMIT` đồng bộ với giới hạn bộ nhớ của container (giữ vùng nhớ heap ở mức khoảng 70-75% so với memory limit).
- **Các container phụ trợ (Sidecars)** (như istio-proxy, trình đẩy log) cần được tính toán định mức riêng biệt; thông số của chúng sẽ được nhân lên theo từng bản sao (replica) của ứng dụng.
- **HPA dựa trên CPU** thực hiện co giãn dựa trên tỷ lệ giữa mức sử dụng thực tế chia cho thông số request. Việc hạ thấp thông số request sẽ khiến HPA kích hoạt nhân bản (scale out) sớm hơn, vì vậy bạn có thể cần hạ mục tiêu `averageUtilization` hoặc số lượng bản sao sẽ thay đổi. Hãy tối ưu hóa định mức tài nguyên trước, sau đó tinh chỉnh lại HPA.

## Giới hạn của phương pháp này
- Các chỉ số phân vị trong một khung thời gian sẽ bỏ sót các sự kiện hiếm gặp: tác vụ tổng hợp dữ liệu hàng tháng, đợt siêu khuyến mãi, hoặc quá trình dựng lại bộ nhớ đệm (cache rebuild) ngay sau khi triển khai bản mới.
- Mức sử dụng trên mỗi container thường được tính trung bình qua các bản sao (replicas); một phân mảnh nóng (hot shard) hoặc một pod đóng vai trò nút trưởng (leader pod) cần được tách thành một dòng dữ liệu riêng.
- Khả năng xếp khối trên node (node bin-packing), phần tài nguyên tiêu hao cho các DaemonSet và dung lượng bộ nhớ thực tế có thể cấp phát (allocatable memory) mới là yếu tố quyết định mức tiết kiệm thực sự; lượng tài nguyên requests được giải phóng chỉ thực sự chuyển hóa thành tiền tiết kiệm được khi số lượng node giảm xuống.
FILE:references/rollout-and-guardrails.md
# Triển khai và Các Rào chắn An toàn (Rollout and Guardrails)

## Thứ tự thực hiện thay đổi
1. **Khắc phục rủi ro trước tiên:** xử lý các trường hợp bị OOM kill, mức bộ nhớ p95 vượt quá request, bị bóp CPU nặng, hoặc thiếu khai báo requests. Những lỗi này trực tiếp gây ra sự cố hệ thống; việc tiết kiệm chi phí có thể đợi sau.
2. **Sau đó mới cắt giảm lãng phí:** xử lý các container bị cấp phát dư thừa (`OVERPROVISIONED`), ưu tiên những dịch vụ có số lượng bản sao (replica) lớn nhất trước vì mức tiết kiệm sẽ được nhân lên theo số bản sao.
3. **Thực hiện từng workload một,** áp dụng trên môi trường thử nghiệm (staging) trước nếu nơi đó có lưu lượng truy cập sát thực tế, sau đó mới đưa lên môi trường chính thức (production) vào khung giờ thấp điểm.

## Các bước triển khai an toàn
1. Thay đổi thông số requests và limits thông qua Git (trong tệp Helm values, bản vá Kustomize hoặc tệp manifest), tuyệt đối không dùng lệnh `kubectl edit` trực tiếp trên môi trường production.
2. Duy trì tốc độ triển khai cuốn chiếu từ từ: thiết lập `maxUnavailable: 0`, `maxSurge: 25%` kèm theo một `PodDisruptionBudget`, để các pod mới với kích thước tài nguyên mới khởi chạy thành công trước khi các pod cũ bị hủy.
3. Theo dõi sát sao trong 24-48 giờ: độ trễ p95, tỷ lệ lỗi, tỷ lệ bóp CPU (throttling), số lần OOM kill, số lần khởi động lại, số lần bị trục xuất (evictions) và số lượng bản sao do HPA điều chỉnh.
4. Hoàn tác (Rollback) = đảo ngược lại bản commit (revert commit). Việc hạ thấp thông số request không bao giờ tự giết chết các pod đang chạy, nhưng các pod sẽ được tạo lại mới trong quá trình triển khai (rollout).

## Ví dụ bản vá cấu hình (patch)
```yaml
resources:
  requests:
    cpu: 485m
    memory: 912Mi
  limits:
    memory: 1136Mi   # no cpu limit on purpose: avoid CFS throttling
```

## Các rào chắn bảo vệ cụm (Cluster guardrails)
- **LimitRange** trên từng namespace: áp đặt mức requests mặc định và giới hạn bộ nhớ mặc định, nhằm ngăn chặn sự xuất hiện của các pod thuộc hạng BestEffort.
- **ResourceQuota** trên từng namespace: khống chế tổng lượng tài nguyên requests tối đa để một nhóm đơn lẻ không thể chiếm hết toàn bộ tài nguyên của cụm.
- **Vertical Pod Autoscaler (VPA)** ở chế độ `updateMode: "Off"` giúp đưa ra các con số khuyến nghị để đối chiếu với kết quả của kỹ năng này mà không tự động khởi động lại các pod. Không được để VPA (chế độ Auto) và HPA theo dõi CPU hoặc bộ nhớ cùng lúc điều khiển chung một workload.
- **Cảnh báo (Alerts):** có sự kiện OOMKilled trong vòng một giờ qua, tỷ lệ bóp CPU vượt quá 25% kéo dài trong 15 phút, bộ nhớ làm việc (working set) vượt quá 90% ngưỡng limit, hoặc có các pod bị treo ở trạng thái Pending do thiếu tài nguyên.

## Khi nào không nên cắt giảm
- Các workload có những đợt tăng tải đột biến hiếm gặp đã biết trước nhưng chưa xuất hiện trong khoảng thời gian lấy mẫu dữ liệu (chốt sổ cuối tháng, Black Friday, chạy báo cáo quý).
- Các pod có giai đoạn khởi động tiêu tốn nhiều CPU hơn hẳn so với trạng thái chạy ổn định (ví dụ quá trình khởi động làm nóng của JVM): hãy giữ mức request cao hơn hoặc sử dụng cơ chế kiểm tra khởi động (startup probe) với độ trễ rộng rãi.
- Các hệ quản trị cơ sở dữ liệu và bộ nhớ đệm đã được cấu hình cứng kích thước bộ nhớ bên trong (như `maxmemory` của Redis, `shared_buffers` của PostgreSQL): giới hạn bộ nhớ (memory limit) của container bắt buộc phải luôn cao hơn kích thước đã cấu hình cộng với phần bộ nhớ phụ trợ (overhead).
- Các trường hợp chủ đích cần hạng chất lượng dịch vụ Guaranteed QoS (ứng dụng đòi hỏi độ trễ cực thấp, ghim cố định lõi CPU với chính sách static CPU manager): hãy giữ nguyên thông số requests bằng đúng với limits.

## Chuyển hóa lượng requests giải phóng thành tiền tiết kiệm thực tế
Lượng tài nguyên requests được giải phóng chỉ thực sự làm giảm hóa đơn chi phí khi bộ tự động co giãn cụm (cluster autoscaler hoặc Karpenter) có thể gom pod và gỡ bỏ bớt các node dư thừa. Hãy kiểm tra hiệu suất sử dụng node theo tỷ lệ requests sau khi áp dụng thay đổi và chờ khoảng một ngày để quá trình dồn nén (consolidation) diễn ra. Hãy luôn báo cáo mức tiết kiệm là "lượng requests được giải phóng" cho đến khi số lượng node thực sự giảm xuống.
FILE:templates/rightsizing-plan.md
# Kế hoạch Tối ưu hóa Định mức Tài nguyên (Rightsizing Plan) - <cluster / namespace> - <ngày>

**Nguồn dữ liệu:** <Prometheus / Datadog / khác>, từ <ngày đầu> đến <ngày cuối> (<n> ngày)  **Dự phòng (Headroom):** <15>%  **Người phụ trách:** <tên>

## Các rủi ro cần khắc phục trước tiên
| Container | Phát hiện | Bằng chứng | Thay đổi | Hạn hoàn thành |
|---|---|---|---|---|
| | | | | |

## Thông số Requests và Limits
| Container | Replicas | CPU req (hiện tại -> mới) | CPU limit | Mem req (hiện tại -> mới) | Mem limit (hiện tại -> mới) | Trạng thái |
|---|---|---|---|---|---|---|
| | | | | | | |

## Mức tiết kiệm ước tính
- Tài nguyên requests giải phóng được: <cores> cores, <GiB> GiB
- Mức tiết kiệm hàng tháng ước tính: <số tiền> (tính theo đơn giá <giá mỗi core> / <giá mỗi GiB>); chỉ thành tiền thực tế sau khi cụm thu giảm số lượng node

## Lộ trình triển khai (Rollout)
| Bước | Workload | Môi trường | Ngày | Chỉ số theo dõi | Phương án hoàn tác (Rollback) |
|---|---|---|---|---|---|
| 1 | | staging | | độ trễ, OOM, throttling | revert commit |

## Các bước theo dõi tiếp theo
- Đo đạc lại vào ngày <ngày> với số liệu phân vị mới
- Rào chắn an toàn (Guardrails): thiết lập mặc định LimitRange <...>, cảnh báo <...>
FILE:examples/shop-cluster-usage.csv
namespace,workload,container,replicas,cpu_request_m,cpu_limit_m,mem_request_mi,mem_limit_mi,cpu_p50_m,cpu_p95_m,cpu_max_m,mem_p50_mi,mem_p95_mi,mem_max_mi,throttled_pct,oom_kills,days
shop,checkout-api,app,6,1000,2000,2048,2048,180,420,1350,610,780,905,0,0,14
shop,checkout-api,istio-proxy,6,100,2000,128,1024,35,90,240,70,95,120,0,0,14
shop,catalog-search,app,4,500,500,1024,1536,310,495,500,900,1180,1490,31,3,14
shop,image-resizer,worker,3,250,1000,512,,120,380,950,340,610,1720,4,0,14
shop,cart-redis,redis,1,200,,768,1024,40,75,160,690,712,730,0,0,14
ops,log-shipper,fluent-bit,8,,,,,25,60,180,45,70,95,0,0,5
FILE:scripts/rightsize.py
#!/usr/bin/env python3
"""Kubernetes resource requests rightsizer (Python 3 standard library only).

Input: CSV with a header row, one row per container, columns
  namespace,workload,container,replicas,
  cpu_request_m,cpu_limit_m,mem_request_mi,mem_limit_mi,
  cpu_p50_m,cpu_p95_m,cpu_max_m,mem_p50_mi,mem_p95_mi,mem_max_mi,
  throttled_pct,oom_kills,days
CPU in millicores (m), memory in MiB (Mi). Empty request/limit cells mean "not set".
throttled_pct = share of CFS periods throttled (0-100); oom_kills and days may be empty (0 / unknown).

Recommendation per container (headroom default 15%, --headroom):
  cpu request  = p95 x (1 + headroom), rounded up to 5m, at least 10m
  cpu limit    = none (recommended), unless --keep-cpu-limits: max(cpu max x 1.2, 2 x request), 50m steps
  mem request  = p95 x (1 + headroom), rounded up to 16Mi, at least 32Mi
  mem limit    = max(mem max x 1.25, request), rounded up to 16Mi (never removed)
Findings (severity):
  CRITICAL OOM_RISK           OOM kills seen, or memory max >= 95% of the memory limit
  HIGH     NO_REQUESTS        cpu or memory request missing (BestEffort / poor scheduling)
  HIGH     MEM_UNDER_REQUEST  memory p95 above the memory request (eviction risk under node pressure)
  HIGH     CPU_THROTTLED      throttled_pct >= 25
  MEDIUM   CPU_THROTTLED      throttled_pct 10-25
  MEDIUM   CPU_UNDER_REQUEST  cpu p95 above 1.2 x cpu request (noisy neighbours, slow under load)
  MEDIUM   NO_MEMORY_LIMIT    memory limit missing (one leak can take the node down)
  LOW      OVERPROVISIONED    recommended cpu or memory request < 50% of current
  LOW      SHORT_WINDOW       under 7 days of data (misses weekly peaks; trust less)
Savings: (current - recommended requests) x replicas, totals in cores and GiB, and a monthly
estimate when --core-month and --gib-month prices are given.
Usage:
  python3 rightsize.py usage.csv
  python3 rightsize.py usage.csv --headroom 25 --core-month 24 --gib-month 3.2 --json
  python3 rightsize.py --self-test
Exit code: 0 no CRITICAL/HIGH, 1 CRITICAL or HIGH findings, 2 bad input.
"""
import argparse
import csv
import io
import json
import math
import sys

COLUMNS = ("namespace", "workload", "container", "replicas", "cpu_request_m", "cpu_limit_m",
           "mem_request_mi", "mem_limit_mi", "cpu_p50_m", "cpu_p95_m", "cpu_max_m",
           "mem_p50_mi", "mem_p95_mi", "mem_max_mi", "throttled_pct", "oom_kills", "days")
OPTIONAL = {"cpu_request_m", "cpu_limit_m", "mem_request_mi", "mem_limit_mi", "throttled_pct", "oom_kills", "days"}
SEV_ORDER = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}


class DataError(ValueError):
    pass


def up(x, step):
    return int(math.ceil(x / step - 1e-9) * step)


def num(row, col, line):
    v = row.get(col, "")
    if v == "":
        if col in OPTIONAL:
            return None
        raise DataError(f"line {line}: {col} is required")
    try:
        x = float(v)
    except ValueError:
        raise DataError(f"line {line}: {col} must be a number, got {v!r}")
    if x < 0:
        raise DataError(f"line {line}: {col} must be >= 0")
    return x


def read_rows(text):
    rd = csv.DictReader(io.StringIO(text))
    if not rd.fieldnames:
        raise DataError("empty CSV")
    missing = [c for c in COLUMNS if c not in {f.strip() for f in rd.fieldnames}]
    if missing:
        raise DataError("CSV header is missing: " + ", ".join(missing))
    rows = []
    for n, raw in enumerate(rd, start=2):
        row = {k.strip(): (v or "").strip() for k, v in raw.items() if k}
        if not any(row.values()):
            continue
        r = {c: row[c] for c in ("namespace", "workload", "container")}
        for c in COLUMNS[3:]:
            r[c] = num(row, c, n)
        if r["replicas"] < 1:
            raise DataError(f"line {n}: replicas must be >= 1")
        if r["cpu_p95_m"] > r["cpu_max_m"] or r["mem_p95_mi"] > r["mem_max_mi"]:
            raise DataError(f"line {n}: p95 cannot be above max")
        rows.append(r)
    if not rows:
        raise DataError("no data rows")
    return rows


def analyze(r, headroom=0.15, keep_cpu_limits=False):
    h = 1 + headroom
    rec = {
        "cpu_request_m": max(10, up(r["cpu_p95_m"] * h, 5)),
        "mem_request_mi": max(32, up(r["mem_p95_mi"] * h, 16)),
    }
    rec["cpu_limit_m"] = max(up(r["cpu_max_m"] * 1.2, 50), up(2 * rec["cpu_request_m"], 50)) if keep_cpu_limits else None
    rec["mem_limit_mi"] = max(rec["mem_request_mi"], up(r["mem_max_mi"] * 1.25, 16))
    findings = []

    def f(sev, code, msg):
        findings.append({"severity": sev, "code": code, "message": msg})

    cr, cl, mr, ml = r["cpu_request_m"], r["cpu_limit_m"], r["mem_request_mi"], r["mem_limit_mi"]
    oom = r["oom_kills"] or 0
    if oom > 0:
        f("CRITICAL", "OOM_RISK", f"{oom:g} OOM kill(s); memory max {r['mem_max_mi']:g}Mi vs limit {fmt(ml, 'Mi')}")
    elif ml and r["mem_max_mi"] >= 0.95 * ml:
        f("CRITICAL", "OOM_RISK", f"memory max {r['mem_max_mi']:g}Mi is {r['mem_max_mi'] / ml:.0%} of the {ml:g}Mi limit")
    if cr is None or mr is None:
        f("HIGH", "NO_REQUESTS", "missing " + " and ".join(x for x, v in (("cpu request", cr), ("memory request", mr)) if v is None))
    if mr and r["mem_p95_mi"] > mr:
        f("HIGH", "MEM_UNDER_REQUEST", f"memory p95 {r['mem_p95_mi']:g}Mi > request {mr:g}Mi")
    th = r["throttled_pct"] or 0
    if th >= 25:
        f("HIGH", "CPU_THROTTLED", f"{th:g}% of CPU periods throttled at limit {fmt(cl, 'm')}; usage is capped, so real demand is higher")
    elif th >= 10:
        f("MEDIUM", "CPU_THROTTLED", f"{th:g}% of CPU periods throttled at limit {fmt(cl, 'm')}")
    if cr and r["cpu_p95_m"] > 1.2 * cr:
        f("MEDIUM", "CPU_UNDER_REQUEST", f"cpu p95 {r['cpu_p95_m']:g}m > 1.2 x request {cr:g}m")
    if ml is None:
        f("MEDIUM", "NO_MEMORY_LIMIT", "no memory limit set")
    over = []
    if cr and rec["cpu_request_m"] < 0.5 * cr:
        over.append(f"cpu {cr:g}m -> {rec['cpu_request_m']}m")
    if mr and rec["mem_request_mi"] < 0.5 * mr:
        over.append(f"memory {mr:g}Mi -> {rec['mem_request_mi']}Mi")
    if over:
        f("LOW", "OVERPROVISIONED", "; ".join(over))
    if r["days"] is not None and r["days"] < 7:
        f("LOW", "SHORT_WINDOW", f"only {r['days']:g} days of data")
    findings.sort(key=lambda x: SEV_ORDER[x["severity"]])
    status = findings[0]["severity"] if findings and findings[0]["severity"] != "LOW" else "OK"
    n = r["replicas"]
    d_cpu = ((cr or 0) - rec["cpu_request_m"]) * n
    d_mem = ((mr or 0) - rec["mem_request_mi"]) * n
    return {"id": f"{r['namespace']}/{r['workload']}/{r['container']}", "replicas": int(n), "current": {
        "cpu_request_m": cr, "cpu_limit_m": cl, "mem_request_mi": mr, "mem_limit_mi": ml},
        "recommended": rec, "delta_cpu_m": d_cpu, "delta_mem_mi": d_mem, "status": status, "findings": findings}


def run(text, headroom=0.15, keep_cpu_limits=False, core_month=None, gib_month=None):
    res = [analyze(r, headroom, keep_cpu_limits) for r in read_rows(text)]
    res.sort(key=lambda x: (SEV_ORDER.get(x["status"], 4), x["id"]))
    tot_cpu = sum(x["delta_cpu_m"] for x in res) / 1000
    tot_mem = sum(x["delta_mem_mi"] for x in res) / 1024
    out = {"containers": res, "freed_cores": round(tot_cpu, 3), "freed_gib": round(tot_mem, 3)}
    if core_month is not None and gib_month is not None:
        out["monthly_saving"] = round(tot_cpu * core_month + tot_mem * gib_month, 2)
    return out


def fmt(v, unit):
    return "none" if v is None else f"{v:g}{unit}"


def report(out, headroom):
    L = ["# Kubernetes rightsizing report", "",
         f"Requests = p95 + {headroom:.0%} headroom; CPU limits removed unless kept; memory limit = max x 1.25.", "",
         "| Container | Replicas | Status | CPU req | CPU limit | Mem req | Mem limit |",
         "|---|---|---|---|---|---|---|"]
    for x in out["containers"]:
        c, r = x["current"], x["recommended"]
        L.append(f"| {x['id']} | {x['replicas']} | {x['status']} | {fmt(c['cpu_request_m'], 'm')} -> {r['cpu_request_m']}m"
                 f" | {fmt(c['cpu_limit_m'], 'm')} -> {fmt(r['cpu_limit_m'], 'm')}"
                 f" | {fmt(c['mem_request_mi'], 'Mi')} -> {r['mem_request_mi']}Mi"
                 f" | {fmt(c['mem_limit_mi'], 'Mi')} -> {r['mem_limit_mi']}Mi |")
    L += ["", "## Findings"]
    any_f = False
    for x in out["containers"]:
        for f in x["findings"]:
            any_f = True
            L.append(f"- {f['severity']} {f['code']} {x['id']}: {f['message']}")
    if not any_f:
        L.append("- none")
    L += ["", "## Requests freed (negative = more needed)",
          f"- CPU: {out['freed_cores']:g} cores", f"- Memory: {out['freed_gib']:g} GiB"]
    if "monthly_saving" in out:
        L.append(f"- Estimated monthly saving: {out['monthly_saving']:,.2f}")
    return "\n".join(L) + "\n"


def self_test():
    cases = []

    def ok(name, cond):
        cases.append(bool(cond))
        print(("PASS " if cond else "FAIL ") + name)

    hdr = ",".join(COLUMNS) + "\n"

    def row(**kw):
        base = dict(namespace="ns", workload="w", container="c", replicas=1, cpu_request_m=500, cpu_limit_m=1000,
                    mem_request_mi=512, mem_limit_mi=1024, cpu_p50_m=100, cpu_p95_m=200, cpu_max_m=300,
                    mem_p50_mi=200, mem_p95_mi=300, mem_max_mi=400, throttled_pct=0, oom_kills=0, days=14)
        base.update(kw)
        return ",".join("" if base[c] is None else str(base[c]) for c in COLUMNS) + "\n"

    def one(**kw):
        return run(hdr + row(**kw))["containers"][0]

    def codes(x):
        return {(f["severity"], f["code"]) for f in x["findings"]}

    x = one()
    ok("cpu request = p95 x 1.15 rounded to 5m (230)", x["recommended"]["cpu_request_m"] == 230)
    ok("mem request = 300 x 1.15 = 345 -> 352Mi", x["recommended"]["mem_request_mi"] == 352)
    ok("mem limit = 400 x 1.25 = 500 -> 512Mi", x["recommended"]["mem_limit_mi"] == 512)
    ok("cpu limit removed by default", x["recommended"]["cpu_limit_m"] is None)
    ok("healthy container is OK", x["status"] == "OK")
    ok("headroom 0.25 changes cpu request (250)", run(hdr + row(), headroom=0.25)["containers"][0]["recommended"]["cpu_request_m"] == 250)
    k = run(hdr + row(), keep_cpu_limits=True)["containers"][0]["recommended"]["cpu_limit_m"]
    ok("kept cpu limit = max(360->400, 460->500) = 500", k == 500)
    ok("minimums 10m / 32Mi", one(cpu_p50_m=0, cpu_p95_m=1, cpu_max_m=2, mem_p50_mi=1, mem_p95_mi=2, mem_max_mi=3)["recommended"]
       == {"cpu_request_m": 10, "mem_request_mi": 32, "cpu_limit_m": None, "mem_limit_mi": 32})
    ok("OOM kills -> CRITICAL", ("CRITICAL", "OOM_RISK") in codes(one(oom_kills=2)) and one(oom_kills=2)["status"] == "CRITICAL")
    ok("max at 98% of limit -> OOM_RISK", ("CRITICAL", "OOM_RISK") in codes(one(mem_max_mi=1004, mem_p95_mi=500)))
    ok("missing requests -> HIGH NO_REQUESTS", ("HIGH", "NO_REQUESTS") in codes(one(cpu_request_m=None)))
    ok("mem p95 above request -> HIGH", ("HIGH", "MEM_UNDER_REQUEST") in codes(one(mem_request_mi=256)))
    ok("throttling 30% -> HIGH", ("HIGH", "CPU_THROTTLED") in codes(one(throttled_pct=30)))
    ok("throttling 12% -> MEDIUM", ("MEDIUM", "CPU_THROTTLED") in codes(one(throttled_pct=12)))
    ok("cpu p95 > 1.2 x request -> MEDIUM", ("MEDIUM", "CPU_UNDER_REQUEST") in codes(one(cpu_request_m=150)))
    ok("no memory limit -> MEDIUM", ("MEDIUM", "NO_MEMORY_LIMIT") in codes(one(mem_limit_mi=None)))
    big = one(cpu_request_m=2000, mem_request_mi=4096)
    ok("overprovisioned flagged LOW, status stays OK", ("LOW", "OVERPROVISIONED") in codes(big) and big["status"] == "OK")
    ok("short window flagged", ("LOW", "SHORT_WINDOW") in codes(one(days=3)))
    two = run(hdr + row(replicas=3) + row(workload="b", replicas=2, cpu_request_m=100, mem_request_mi=256),
              core_month=20, gib_month=4)
    # w: (500-230)*3=810m, (512-352)*3=480Mi ; b: (100-230)*2=-260m, (256-352)*2=-192Mi
    ok("freed cores = (810-260)/1000 = 0.55", two["freed_cores"] == 0.55)
    ok("freed GiB = (480-192)/1024 = 0.281", two["freed_gib"] == 0.281)
    ok("monthly saving = 0.55 x 20 + 0.28125 x 4 = 12.125", abs(two["monthly_saving"] - 12.125) < 0.01)
    ok("sorted by severity", two["containers"][0]["id"] == "ns/b/c")
    for bad, label in (("a,b\n1,2\n", "missing columns"), (hdr, "no rows"), (hdr + row(cpu_p95_m="x"), "bad number"),
                       (hdr + row(cpu_p95_m=900), "p95 above max"), (hdr + row(replicas=0), "zero replicas"),
                       (hdr + row(cpu_p95_m=None), "missing usage")):
        try:
            run(bad)
            ok(label + " rejected", False)
        except DataError:
            ok(label + " rejected", True)
    print(f"{sum(cases)}/{len(cases)} passed")
    return 0 if all(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Rightsize Kubernetes container requests and limits from usage percentiles.")
    ap.add_argument("file", nargs="?", help="CSV with the columns listed in the module docstring")
    ap.add_argument("--headroom", type=float, default=15, help="percent added to p95 for requests (default 15)")
    ap.add_argument("--keep-cpu-limits", action="store_true", help="recommend CPU limits instead of removing them")
    ap.add_argument("--core-month", type=float, help="price of one requested core per month")
    ap.add_argument("--gib-month", type=float, help="price of one requested GiB of memory per month")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        ap.error("give a CSV file or --self-test")
    try:
        out = run(open(a.file, encoding="utf-8").read(), a.headroom / 100, a.keep_cpu_limits, a.core_month, a.gib_month)
    except (OSError, DataError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(out, indent=2) if a.json else report(out, a.headroom / 100), end="\n" if a.json else "")
    return 1 if any(x["status"] in ("CRITICAL", "HIGH") for x in out["containers"]) else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: backup-retention-policy-planner
description: Lập kế hoạch và kiểm toán các chính sách lưu giữ bản sao lưu (ông-cha-con / grandfather-father-son). Mô phỏng các quy tắc giữ lại theo giờ, ngày, tuần, tháng và năm giống như restic hoặc borg, liệt kê các điểm khôi phục thực sự được giữ lại và khoảng trống giữa chúng, đồng thời ước tính dung lượng lưu trữ và chi phí hiện tại cũng như trong 12 tháng tới. Đánh dấu RPO bị bỏ lỡ, lịch sử ngắn, thiếu hụt lưu giữ pháp lý, không có bản sao ngoài cơ sở (offsite) hoặc bất biến (immutable), các bài kiểm tra khôi phục đã cũ và sự chồng chéo tác vụ. Bao gồm một trình lập kế hoạch Python dùng thư viện chuẩn với tùy chọn --self-test.
---

# Trình lập kế hoạch chính sách lưu giữ bản sao lưu

Bạn giúp các kỹ sư và các nhóm CNTT nhỏ thiết kế một chính sách lưu giữ bản sao lưu mà họ có thể bảo vệ được: đủ điểm khôi phục để phục hồi từ sai lầm ngày hôm qua và lỗi hỏng dữ liệu âm thầm từ quý trước, một bản sao sống sót qua cuộc tấn công ransomware hoặc mất tài khoản, hóa đơn lưu trữ vừa với ngân sách, và quy trình khôi phục thực sự đã được kiểm thử. Bạn biến quy tắc "giữ 7 bản hàng ngày, 4 bản hàng tuần, 12 bản hàng tháng" thành danh sách cụ thể các điểm khôi phục mà nó tạo ra và đối chiếu với các yêu cầu.

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

- `scripts/retention_plan.py` - mô phỏng chính sách GFS, liệt kê các điểm khôi phục được giữ lại, các khoảng trống, dung lượng lưu trữ và chi phí, đồng thời in ra các phát hiện (chỉ dùng thư viện chuẩn Python 3)
- `references/retention-design.md` - cách các quy tắc giữ lại chọn điểm khôi phục, cách chọn các bậc (tier) từ nhu cầu RPO và lịch sử, lưu giữ pháp lý, các mô hình lưu trữ và chi phí
- `references/resilience-checklist.md` - quy tắc 3-2-1-1-0, tính bất biến (immutability), mã hóa và khóa, kiểm thử khôi phục, giám sát và ý nghĩa của từng phát hiện
- `templates/backup-policy.md` - mẫu chính sách sao lưu dài một trang để điền vào và chia sẻ với nhóm
- `examples/clinic-postgres-policy.json` - cơ sở dữ liệu PostgreSQL được sao lưu hàng đêm lên S3 với RPO 4 giờ và thời gian lưu giữ pháp lý 3 năm

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

### 1. Thu thập thông tin thực tế
Hỏi về: những gì được sao lưu và bằng cách nào (công cụ, sao lưu toàn phần hay tăng dần), tần suất sao lưu và thời gian chạy một lần mất bao lâu, các quy tắc giữ lại hiện tại, kích thước dữ liệu, tỷ lệ thay đổi hàng ngày và mức tăng trưởng, nơi lưu trữ các bản sao (tại chỗ, ngoài cơ sở, bất biến/khóa đối tượng, được mã hóa), giá lưu trữ, ngày kiểm thử khôi phục thành công gần nhất, và các yêu cầu: RPO (mức mất dữ liệu tối đa), họ phải có khả năng khôi phục lùi về quá khứ bao xa, bất kỳ yêu cầu lưu giữ pháp lý hoặc theo hợp đồng nào, và ngân sách lưu trữ. Nếu họ không biết tỷ lệ thay đổi, hãy bắt đầu với mức 2-5% mỗi ngày đối với cơ sở dữ liệu và 1% đối với chia sẻ tệp, đồng thời nêu rõ giả định đó.

### 2. Chạy trình lập kế hoạch
```
python3 scripts/retention_plan.py examples/clinic-postgres-policy.json
python3 scripts/retention_plan.py policy.json --json
python3 scripts/retention_plan.py --self-test
```
Mã thoát 1 có nghĩa là có các phát hiện mức HIGH, 2 có nghĩa là đầu vào không hợp lệ.

### 3. Giải thích kết quả
Bắt đầu với các điểm khôi phục mà họ thực sự có (số lượng, bản cũ nhất, các khoảng trống lớn nhất) vì hầu hết mọi người đều đánh giá quá cao chúng. Sau đó đi qua các phát hiện theo mức độ nghiêm trọng bằng cách sử dụng `references/retention-design.md` và `references/resilience-checklist.md`, đồng thời đưa ra một thay đổi cụ thể cho từng vấn đề: quy tắc giữ lại mới, vận chuyển WAL hoặc nhật ký (log shipping) cho RPO chặt chẽ, khóa đối tượng (object lock), ngày diễn tập khôi phục. Chạy lại trình lập kế hoạch với chính sách được đề xuất và hiển thị dung lượng lưu trữ cũng như chi phí trước và sau khi thay đổi.

### 4. Bàn giao
Điền vào `templates/backup-policy.md` với các quy tắc giữ lại cuối cùng, các bản sao, yêu cầu, kế hoạch kiểm thử khôi phục và người phụ trách.

## Kết quả ví dụ
Đối với `examples/clinic-postgres-policy.json` (sao lưu hàng đêm, giữ 7 bản hàng ngày, 4 bản hàng tuần, 6 bản hàng tháng): 14 điểm khôi phục, bản cũ nhất 4,8 tháng, khoảng trống lên tới 31 ngày sau tháng đầu tiên, 968 GB hiện tại và 1550 GB sau 12 tháng (22,27 đến 35,66 USD/tháng). Các phát hiện: HIGH RPO_MISSED (sao lưu 24 giờ một lần so với RPO 4 giờ; cần thêm lưu trữ WAL hoặc sao lưu tăng dần mỗi 4 giờ), HIGH LEGAL_RETENTION (cần 3 năm; hãy đặt bậc hàng năm thành 5), MEDIUM RESTORE_TEST_OLD (193 ngày), MEDIUM NO_IMMUTABLE, MEDIUM STORAGE_OVER (1550 GB so với ngân sách 1500 GB sau 12 tháng).

## Quy tắc

- Một bản sao lưu chưa bao giờ được khôi phục thử thì chưa được chứng minh là hoạt động. Luôn hỏi về lần kiểm thử khôi phục gần nhất và khuyến nghị một buổi diễn tập có bấm giờ.
- Các quy tắc giữ lại đếm theo các khung thời gian (bucket), không phải số ngày: "monthly 12" giữ lại bản sao lưu mới nhất của mỗi tháng trong 12 tháng gần nhất có bản sao lưu, bao gồm cả tháng hiện tại.
- Nêu rõ mô hình lưu trữ mà bạn đã giả định; ước tính sao lưu tăng dần (incremental) là mức trần vì việc chống trùng lặp (deduplication) và các thay đổi khối lặp đi lặp lại làm cho kích thước thực tế nhỏ hơn.
- RPO được quyết định bởi tần suất sao lưu (hoặc log shipping), không phải bởi thời gian lưu giữ; độ sâu lịch sử được quyết định bởi thời gian lưu giữ, không phải bởi tần suất.
- Không bao giờ đề xuất xóa các bản sao lưu hiện có cho đến khi chính sách mới đã chạy và việc khôi phục từ chính sách đó đã được kiểm thử.
FILE:references/retention-design.md
# Thiết kế chính sách lưu giữ

## Cách các quy tắc giữ lại chọn điểm khôi phục
Các công cụ như restic (`forget --keep-daily 7 --keep-weekly 4`), borg (`prune --keep-daily 7`), pgBackRest và hầu hết các thiết bị sao lưu chuyên dụng đều sử dụng chung một ý tưởng. Đối với mỗi bậc (tier), duyệt qua các bản sao lưu từ mới nhất đến cũ nhất và giữ lại một bản sao lưu khi khung thời gian (bucket) của nó khác với bản cuối cùng được giữ lại bởi bậc đó, cho đến khi dùng hết số lượng của bậc đó:

| Bậc | Khung thời gian (Bucket) | "giữ N" có nghĩa là |
|---|---|---|
| hourly | giờ theo lịch | bản sao lưu mới nhất của mỗi giờ trong N giờ gần nhất có bản sao lưu |
| daily | ngày theo lịch | bản sao lưu mới nhất của mỗi ngày trong N ngày gần nhất |
| weekly | tuần ISO (Thứ Hai đến Chủ Nhật) | bản sao lưu mới nhất của mỗi tuần trong N tuần gần nhất |
| monthly | tháng theo lịch | bản sao lưu mới nhất của mỗi tháng trong N tháng gần nhất |
| yearly | năm theo lịch | bản sao lưu mới nhất của mỗi năm trong N năm gần nhất |

Những hệ quả mà mọi người thường bỏ sót:
- Mọi bậc đều bắt đầu bằng bản sao lưu mới nhất, vì vậy các bậc có sự chồng lấn. 7 daily + 4 weekly + 12 monthly là 20 điểm, không phải 23.
- Tuần, tháng và năm hiện tại mỗi thứ được tính là một khung thời gian. "monthly 12" chỉ lùi về trước khoảng 11 tháng, và "yearly 3" chỉ lùi về đến cuối năm kia (khoảng 1,8 năm nếu tính vào cuối tháng Mười).
- Các điểm hàng tháng là các bản sao lưu cuối tháng (mới nhất trong mỗi tháng), các điểm hàng tuần là các bản sao lưu ngày Chủ Nhật đối với tuần ISO.
- Những ngày không có bản sao lưu không làm tiêu tốn một vị trí (slot) hàng ngày, vì vậy một tuần bị lỗi sẽ kéo dài lịch sử hàng ngày lùi xa hơn về trước nhưng lại để lại một lỗ hổng.

`scripts/retention_plan.py` tái tạo quy tắc này, in ra mọi điểm được giữ lại cùng với các bậc của nó (D/W/M/Y/H) và liệt kê các khoảng trống lớn nhất.

## Chọn các bậc từ yêu cầu
| Yêu cầu | Yếu tố quyết định | Câu trả lời điển hình |
|---|---|---|
| RPO (mức mất dữ liệu tối đa) | tần suất sao lưu hoặc log shipping | 24 giờ: hàng đêm; 1-4 giờ: snapshot hoặc sao lưu tăng dần hàng giờ; tính bằng phút: lưu trữ WAL/binlog của cơ sở dữ liệu với khả năng khôi phục tại một thời điểm (point-in-time recovery) |
| Phục hồi từ sai lầm được phát hiện muộn | độ sâu hàng ngày và hàng tuần | ít nhất 14-35 ngày: khoảng thời gian cần thiết để ai đó nhận ra một đợt triển khai lỗi, một thư mục bị xóa hoặc một lần nhập dữ liệu hỏng |
| Lỗi hỏng dữ liệu âm thầm, kiểm toán | độ sâu hàng tháng | 6-13 tháng |
| Lưu giữ pháp lý hoặc theo hợp đồng | bậc hàng năm hoặc một kho lưu trữ riêng | N năm cần mức yearly N+2 để luôn có một điểm cũ N năm xuyên suốt cả năm; thường tốt hơn nếu tách thành một tác vụ lưu trữ riêng biệt với khóa bảo vệ riêng |
| Ngân sách | mô hình lưu trữ và tỷ lệ thay đổi | xem bên dưới |

Một điểm khởi đầu phổ biến, dễ bảo vệ cho dữ liệu doanh nghiệp: hourly 24 (nếu RPO < 24 giờ), daily 14, weekly 8, monthly 12, yearly theo yêu cầu của pháp luật.

Các khoảng trống: khi một bậc thô bắt đầu rất lâu sau khi bậc chi tiết kết thúc (ví dụ daily 7 rồi nhảy sang monthly), việc khôi phục trong khoảng từ ngày thứ 8 đến cuối tháng sẽ rơi vào một điểm cũ hơn tới 30 ngày so với điểm bạn mong muốn. Hãy thêm các điểm hàng tuần hoặc tăng thêm các điểm hàng ngày (`TIER_GAP`).

## Các mô hình lưu trữ
- **Full (Toàn phần)**: mọi điểm được giữ lại đều là một bản sao hoàn chỉnh (băng từ, các tệp dump đơn giản, một số bản xuất snapshot). Dung lượng lưu trữ = số điểm x kích thước toàn phần.
- **Incremental / deduplicated (Tăng dần / chống trùng lặp)** (restic, borg, pgBackRest incremental, ZFS/EBS snapshot): một bản toàn phần cộng với dữ liệu đã thay đổi giữa các điểm được giữ lại. Trình lập kế hoạch tính `daily_change_pct x days` giữa các điểm liền kề, giới hạn tối đa ở mức 100% kích thước toàn phần. Đây là mức trần: khi cùng các khối dữ liệu đó thay đổi mỗi ngày, khoảng trống một tháng sẽ tốn ít dung lượng hơn nhiều so với 30 ngày thay đổi cộng dồn. Hãy đo các con số thực tế bằng `restic stats --mode raw-data`, `borg info` hoặc hóa đơn lưu trữ và điều chỉnh `daily_change_pct`.
- Mức tăng trưởng: `growth_pct_per_month` tính lãi kép trong 12 tháng để hiển thị dung lượng lưu trữ và chi phí của năm tới.

Các đòn bẩy chi phí, từ rẻ nhất đến có tác động lớn nhất tới khả năng phục hồi: nén và chống trùng lặp; chuyển các điểm hàng tháng và hàng năm sang lớp lưu trữ lạnh hơn (lưu ý thời gian lưu trữ tối thiểu và phí truy xuất); bỏ các điểm hàng giờ sau 2-3 ngày; giảm các điểm hàng tháng sau khi nhu cầu pháp lý đã được đáp ứng bởi một bản lưu trữ hàng năm.

## Ví dụ minh họa
Sao lưu hàng đêm lúc 02:00, giữ daily 7, weekly 4, monthly 6, tính đến ngày 2026-10-24:
- daily: 10-24 lùi về 10-18
- weekly: 10-24 (tuần ISO hiện tại), 10-18, 10-11, 10-04
- monthly: 10-24, 09-30, 08-31, 07-31, 06-30, 05-31
- 14 điểm riêng biệt; bản cũ nhất là 2026-05-31 (khoảng 4,8 tháng); các khoảng trống sau tháng đầu tiên là 30-31 ngày.
FILE:references/resilience-checklist.md
# Danh sách kiểm tra khả năng chống chịu

## Quy tắc 3-2-1-1-0
- **3** bản sao dữ liệu (bản production cộng với hai bản sao lưu)
- **2** loại hoặc hệ thống lưu trữ khác nhau
- **1** bản sao ngoài cơ sở - offsite (một vùng, nhà cung cấp hoặc tòa nhà khác)
- **1** bản sao bất biến hoặc ngoại tuyến (khóa đối tượng ở chế độ tuân thủ, lưu trữ WORM, băng từ lấy ra khỏi thư viện, bản sao lưu dạng kéo mà hệ thống nguồn không thể xóa)
- **0** lỗi trong lần khôi phục đã xác minh gần nhất

## Ý nghĩa của từng phát hiện và cách khắc phục
| Mã | Mức độ nghiêm trọng | Tại sao điều này quan trọng | Cách khắc phục điển hình |
|---|---|---|---|
| RPO_MISSED | HIGH | Sự cố xảy ra ngay trước lần sao lưu tiếp theo làm mất nhiều dữ liệu hơn mức doanh nghiệp chấp nhận | Khoảng thời gian ngắn hơn, sao lưu tăng dần hàng giờ, hoặc vận chuyển nhật ký liên tục (lưu trữ PostgreSQL WAL với pgBackRest/WAL-G, MySQL binlog, sao lưu nhật ký SQL Server) |
| HISTORY_SHORT | HIGH | Các vấn đề được phát hiện muộn (nhập dữ liệu lỗi, thư mục bị xóa, hỏng dữ liệu chậm) không thể hoàn tác | Thêm nhiều điểm hàng ngày/hàng tuần hơn; ít nhất bằng thời gian cần thiết để phát hiện sự cố cộng với một khoảng dự phòng |
| LEGAL_RETENTION | HIGH | Các quy định hợp đồng, thuế hoặc hồ sơ y tế có thể yêu cầu lưu giữ lịch sử nhiều năm | Bậc hàng năm ở mức N+2 hoặc một tác vụ lưu trữ hàng năm riêng biệt có khóa đối tượng được đặt theo thời hạn pháp lý |
| NO_OFFSITE | HIGH | Hỏa hoạn, mất điện toàn vùng hoặc tài khoản bị xâm phạm sẽ xóa sổ cả môi trường production lẫn bản sao lưu cùng lúc | Nhân bản sang vùng/nhà cung cấp khác với thông tin xác thực riêng biệt |
| NEVER_RESTORED | HIGH | Các bản sao lưu thất bại âm thầm: thiếu tệp, sai quyền truy cập, mất khóa mã hóa, sổ tay vận hành (runbook) chưa được kiểm thử | Diễn tập khôi phục ngay; ghi lại thời gian thực hiện (RTO thực tế) |
| OVERLAP | HIGH | Các tác vụ va chạm hoặc bị bỏ qua, khiến khoảng cách thực tế dài hơn kế hoạch | Sao lưu tăng dần, thiết bị lưu trữ nhanh hơn, hoặc khoảng cách dài hơn kết hợp với vận chuyển nhật ký (log shipping) |
| RESTORE_TEST_OLD | MEDIUM | Hệ thống thay đổi liên tục; bài kiểm tra từ mùa xuân năm ngoái không nói lên được nhiều điều về hiện tại | Diễn tập hàng quý; tự động khôi phục và kiểm tra checksum hàng tháng đối với dữ liệu quan trọng |
| NO_IMMUTABLE | MEDIUM | Ransomware và kẻ tấn công luôn xóa các bản sao lưu trước tiên | S3 Object Lock / Azure immutable blob / GCS bucket lock, hoặc một bản sao ngoại tuyến |
| NOT_ENCRYPTED | MEDIUM | Bản sao ngoài cơ sở sẽ làm lộ toàn bộ dữ liệu nếu bucket hoặc băng từ bị phơi bày | Mã hóa phía máy khách (client-side); khóa được lưu trữ bên ngoài hệ thống sao lưu và được ký quỹ (escrow) an toàn |
| STORAGE_OVER | MEDIUM | Ngân sách buộc ai đó phải cắt giảm thời gian lưu giữ một cách vội vàng về sau | Lưu trữ lạnh hơn cho các bậc cũ, giảm bớt các điểm hàng tháng, đo tỷ lệ thay đổi thực tế |
| TIER_GAP | LOW | Việc khôi phục rơi vào khoảng trống sẽ phải dùng điểm cũ hơn nhiều so với mong muốn | Thêm các điểm hàng tuần hoặc kéo dài các điểm hàng ngày |
| TIGHT_WINDOW | LOW | Sự gia tăng dữ liệu sẽ đẩy tác vụ vào tình trạng chồng chéo | Lên kế hoạch sao lưu tăng dần hoặc song song trước khi điều đó xảy ra |

## Diễn tập khôi phục (một trang)
1. Chọn một điểm khôi phục ngẫu nhiên, không phải điểm mới nhất.
2. Khôi phục vào một môi trường cô lập chỉ sử dụng sổ tay vận hành (runbook) và các khóa được ký quỹ.
3. Kiểm tra: số lượng hàng hoặc số lượng tệp, ứng dụng khởi động được, một bản ghi đã biết từ ngày đó có tồn tại.
4. Ghi lại thời gian bắt đầu và kết thúc (RTO thực tế), các vấn đề gặp phải và những điểm cần sửa trong sổ tay vận hành.
5. Xóa bản sao đã khôi phục và ghi nhận ngày diễn tập; trường `last_restore_test` của trình lập kế hoạch chính là ngày này.

## Giám sát
- Cảnh báo khi bản sao lưu mới nhất cũ hơn 1,5 lần khoảng cách định kỳ.
- Cảnh báo khi có các tác vụ thất bại hoặc chỉ hoàn thành một phần, chứ không chỉ khi thiếu bản sao lưu.
- Theo dõi kích thước bản sao lưu mỗi lần chạy; sự sụt giảm đột ngột thường có nghĩa là đường dẫn bao gồm (include path) bị hỏng, sự tăng vọt đột ngột có thể là dấu hiệu bị ransomware mã hóa.
- Kiểm tra xem các tác vụ prune/forget có chạy hay không; một chính sách không bao giờ được thực thi sẽ âm thầm làm đầy bộ nhớ.

## Khóa và quyền truy cập
- Thông tin xác thực sao lưu nên chỉ có quyền ghi (write-only) từ phía nguồn ở những nơi có thể; việc xóa cần một định danh khác.
- Giữ các khóa mã hóa và sổ tay vận hành khôi phục ở nơi vẫn tồn tại được ngay cả khi mất môi trường chính (kho lưu trữ của trình quản lý mật khẩu, bản in niêm phong).
FILE:templates/backup-policy.md
# Chính sách Sao lưu - <system name>

**Chủ sở hữu:** <team / person>  **Đã xem xét:** <date>  **Lần xem xét tiếp theo:** <date + 6 months>

## Phạm vi
- Dữ liệu: <databases, buckets, file shares, configs>
- Loại trừ: <caches, rebuildable artifacts>

## Yêu cầu
| Hạng mục | Mục tiêu | Nguồn yêu cầu |
|---|---|---|
| RPO (mức mất dữ liệu tối đa) | <4 h> | <business owner> |
| RTO (thời gian khôi phục tối đa) | <2 h> | <business owner> |
| Lịch sử tối thiểu | <35 days> | <ops> |
| Lưu giữ pháp lý / theo hợp đồng | <3 years> | <contract, regulation> |
| Ngân sách lưu trữ | <1500 GB / 40 USD per month> | <finance> |

## Lịch trình và quy tắc giữ lại
| Tác vụ | Tần suất | Phương thức | Quy tắc giữ lại |
|---|---|---|---|
| <full/incremental> | <daily 02:00> | <pgBackRest incr to S3> | <daily 14, weekly 8, monthly 12, yearly 5> |
| <log shipping> | <continuous> | <WAL archive> | <14 days> |

Các điểm khôi phục được tạo ra (từ `scripts/retention_plan.py`): <count>, bản cũ nhất <age>, khoảng trống lớn nhất <days>.

## Các bản sao (3-2-1-1-0)
| Bản sao | Vị trí | Bất biến | Mã hóa | Thông tin xác thực |
|---|---|---|---|---|
| Bản sao lưu chính | <region A bucket> | <no> | <yes> | <backup-writer role> |
| Ngoài cơ sở (Offsite) | <region B / provider B> | <object lock 35 d> | <yes> | <separate account> |

## Dung lượng lưu trữ và chi phí
- Hiện tại: <GB> / <cost per month>  - Sau 12 tháng: <GB> / <cost per month>

## Kiểm thử khôi phục
- Tần suất: <quarterly drill, monthly automated check>
- Lần kiểm thử gần nhất: <date>, kết quả <ok / issues>, RTO thực tế <time>
- Sổ tay vận hành (Runbook): <link>  - Khóa được ký quỹ tại: <location>

## Giám sát và cảnh báo
- <newest backup older than 36 h -> page on-call>
- <job failed / size change > 30% -> ticket>

## Các phát hiện đang mở
- <severity code: action, owner, due date>
FILE:examples/clinic-postgres-policy.json
{
  "name": "clinic-booking PostgreSQL (pgBackRest to S3)",
  "today": "2026-10-24",
  "backup_interval_hours": 24,
  "backup_duration_hours": 2.5,
  "policy": {"daily": 7, "weekly": 4, "monthly": 6, "yearly": 0},
  "size": {"full_gb": 180, "daily_change_pct": 3, "growth_pct_per_month": 4, "storage_model": "incremental"},
  "requirements": {
    "rpo_hours": 4,
    "min_history_days": 90,
    "legal_retention_years": 3,
    "max_storage_gb": 1500,
    "restore_test_max_age_days": 90
  },
  "copies": {"onsite": false, "offsite": true, "immutable": false, "encrypted": true},
  "price_per_gb_month": 0.023,
  "currency": "USD",
  "last_restore_test": "2026-04-14"
}
FILE:scripts/retention_plan.py
#!/usr/bin/env python3
"""Backup retention policy planner (Python 3 standard library only).

Simulates a grandfather-father-son (GFS) retention policy the way restic/borg "keep" rules
work, then reports the restore points you really keep, the gaps between them, storage and
cost, and the gaps against your requirements (RPO, minimum history, legal retention, 3-2-1).

Input JSON:
  {"name": "orders-db", "today": "2026-10-24",
   "backup_interval_hours": 24, "backup_duration_hours": 1.5,
   "policy": {"hourly": 0, "daily": 7, "weekly": 4, "monthly": 12, "yearly": 3},
   "size": {"full_gb": 120, "daily_change_pct": 4, "growth_pct_per_month": 3,
            "storage_model": "incremental"},          # or "full" (every point is a full copy)
   "requirements": {"rpo_hours": 24, "min_history_days": 35, "legal_retention_years": 0,
                    "max_storage_gb": 0, "restore_test_max_age_days": 90},
   "copies": {"onsite": true, "offsite": true, "immutable": false, "encrypted": true},
   "price_per_gb_month": 0.023, "currency": "USD",
   "last_restore_test": "2026-03-02"}                 # or null if never tested
Selection rule per tier (newest backup first): keep a backup if its bucket (hour, day, ISO week,
month, year) differs from the previous kept bucket of that tier, until the tier count is used.
A backup kept by several tiers is stored once.
Storage: "full" = points x full size; "incremental" = one full + each later point's changed data
(daily_change_pct x days since the previous kept point, capped at 100%).
Findings (severity):
  HIGH   RPO_MISSED          backup interval longer than the RPO
  HIGH   HISTORY_SHORT       oldest restore point younger than min_history_days
  HIGH   LEGAL_RETENTION     oldest point younger than legal_retention_years
  HIGH   NO_OFFSITE          no offsite copy (breaks 3-2-1)
  HIGH   NEVER_RESTORED      no restore test recorded
  HIGH   OVERLAP             backup takes longer than the interval
  MEDIUM RESTORE_TEST_OLD    last restore test older than restore_test_max_age_days
  MEDIUM NO_IMMUTABLE        no immutable/air-gapped copy (ransomware can delete backups)
  MEDIUM STORAGE_OVER        storage (now or in 12 months) above max_storage_gb
  MEDIUM NOT_ENCRYPTED       offsite copy not encrypted
  LOW    TIER_GAP            a coarse tier starts long after the finer tier ends (e.g. weekly
                             4 then monthly: weeks 5-8 have one point a month)
  LOW    TIGHT_WINDOW        backup duration above 50% of the interval
Usage:
  python3 retention_plan.py policy.json
  python3 retention_plan.py policy.json --json
  python3 retention_plan.py --self-test
Exit code: 0 no HIGH findings, 1 HIGH findings, 2 bad input.
"""
import argparse
import datetime as dt
import json
import sys

TIERS = ["hourly", "daily", "weekly", "monthly", "yearly"]
SEV_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}


class DataError(ValueError):
    pass


def bucket(tier, t):
    if tier == "hourly":
        return t.strftime("%Y-%m-%d %H")
    if tier == "daily":
        return t.date().isoformat()
    if tier == "weekly":
        y, w, _ = t.isocalendar()
        return f"{y}-W{w:02d}"
    if tier == "monthly":
        return t.strftime("%Y-%m")
    return str(t.year)


def simulate(policy, interval_h, today):
    """Return (kept list of (datetime, [tiers])) newest first."""
    for k in policy:
        if k not in TIERS:
            raise DataError(f"unknown policy tier '{k}' (use {', '.join(TIERS)})")
        if not isinstance(policy[k], int) or policy[k] < 0:
            raise DataError(f"policy.{k} must be a whole number >= 0")
    if sum(policy.get(t, 0) for t in TIERS) == 0:
        raise DataError("policy keeps nothing")
    if not interval_h or interval_h <= 0:
        raise DataError("backup_interval_hours must be > 0")
    span_days = max(policy.get("hourly", 0) / 24, policy.get("daily", 0), policy.get("weekly", 0) * 7,
                    policy.get("monthly", 0) * 31, policy.get("yearly", 0) * 366) + 400
    newest = dt.datetime.combine(today, dt.time(2, 0))
    step = dt.timedelta(hours=interval_h)
    n = int(span_days * 24 / interval_h) + 1
    times = [newest - i * step for i in range(n)]
    kept = {}
    for tier in TIERS:
        want = policy.get(tier, 0)
        last = None
        for t in times:
            if want == 0:
                break
            b = bucket(tier, t)
            if b != last:
                kept.setdefault(t, []).append(tier)
                last = b
                want -= 1
    return sorted(kept.items(), key=lambda kv: kv[0], reverse=True)


def storage_gb(kept, size):
    full = float(size.get("full_gb", 0))
    model = size.get("storage_model", "incremental")
    if model not in ("incremental", "full"):
        raise DataError("size.storage_model must be 'incremental' or 'full'")
    if model == "full":
        return full * len(kept)
    change = float(size.get("daily_change_pct", 5)) / 100
    total = full
    for (newer, _), (older, _) in zip(kept, kept[1:]):
        days = (newer - older).total_seconds() / 86400
        total += full * min(1.0, change * days)
    return total


def plan(cfg, today=None):
    try:
        today = today or dt.date.fromisoformat(cfg.get("today") or dt.date.today().isoformat())
    except ValueError:
        raise DataError("today must be YYYY-MM-DD")
    policy = cfg.get("policy") or {}
    interval = float(cfg.get("backup_interval_hours", 24))
    kept = simulate(policy, interval, today)
    newest = kept[0][0]
    ages = [(newest - t).total_seconds() / 86400 for t, _ in kept]
    oldest_days = ages[-1]
    size = cfg.get("size") or {}
    req = cfg.get("requirements") or {}
    copies = cfg.get("copies") or {}
    price = float(cfg.get("price_per_gb_month", 0))
    gb = storage_gb(kept, size)
    growth = float(size.get("growth_pct_per_month", 0)) / 100
    gb12 = gb * (1 + growth) ** 12
    tiers = []
    for tier in TIERS:
        pts = [(t, a) for (t, tl), a in zip(kept, ages) if tier in tl]
        if pts:
            tiers.append({"tier": tier, "count": len(pts), "newest_age_days": round(pts[0][1], 1),
                          "oldest_age_days": round(pts[-1][1], 1)})
    gaps = []
    for (t1, _), (t2, _), a in zip(kept, kept[1:], ages[1:]):
        gaps.append({"from": t2.date().isoformat(), "to": t1.date().isoformat(),
                     "gap_days": round((t1 - t2).total_seconds() / 86400, 1), "age_days": round(a, 1)})
    findings = []

    def add(sev, code, msg):
        findings.append({"severity": sev, "code": code, "message": msg})

    rpo = req.get("rpo_hours")
    if rpo and interval > rpo:
        add("HIGH", "RPO_MISSED", f"backups every {interval:g} h but RPO is {rpo:g} h; up to {interval:g} h of data can be lost")
    mh = req.get("min_history_days")
    if mh and oldest_days < mh:
        add("HIGH", "HISTORY_SHORT", f"oldest restore point is {oldest_days:.0f} days old; requirement is {mh} days")
    ly = req.get("legal_retention_years")
    if ly and oldest_days < ly * 365:
        add("HIGH", "LEGAL_RETENTION", f"oldest point {oldest_days / 365:.1f} years; legal retention needs {ly} years; yearly N also counts the current year, so set yearly >= {ly + 2} to cover it all year round")
    if not copies.get("offsite"):
        add("HIGH", "NO_OFFSITE", "no offsite copy; a site loss, account compromise or region outage takes every backup")
    dur = cfg.get("backup_duration_hours")
    if dur and dur > interval:
        add("HIGH", "OVERLAP", f"backup takes {dur:g} h but runs every {interval:g} h; jobs overlap or get skipped")
    elif dur and dur > interval / 2:
        add("LOW", "TIGHT_WINDOW", f"backup takes {dur:g} h of a {interval:g} h interval; growth will push it into overlap")
    lrt = cfg.get("last_restore_test")
    max_age = req.get("restore_test_max_age_days", 90)
    if not lrt:
        add("HIGH", "NEVER_RESTORED", "no restore test recorded; an untested backup is a hope, not a backup")
    else:
        age = (today - dt.date.fromisoformat(lrt)).days
        if age > max_age:
            add("MEDIUM", "RESTORE_TEST_OLD", f"last restore test {age} days ago (limit {max_age}); schedule a timed restore")
    if not copies.get("immutable"):
        add("MEDIUM", "NO_IMMUTABLE", "no immutable or air-gapped copy; ransomware or a stolen admin key can delete every backup")
    if copies.get("offsite") and copies.get("encrypted") is False:
        add("MEDIUM", "NOT_ENCRYPTED", "offsite copy is not encrypted at rest")
    mx = req.get("max_storage_gb")
    if mx and max(gb, gb12) > mx:
        add("MEDIUM", "STORAGE_OVER", f"storage {gb:.0f} GB now, {gb12:.0f} GB in 12 months; budget {mx} GB")
    order = [t for t in TIERS if policy.get(t, 0) > 0]
    span = {"hourly": 1 / 24, "daily": 1, "weekly": 7, "monthly": 30.4, "yearly": 365}
    for fine, coarse in zip(order, order[1:]):
        fine_end = policy[fine] * span[fine]
        if span[coarse] >= 4 * fine_end and fine != "hourly":
            add("LOW", "TIER_GAP", f"{fine} points cover ~{fine_end:.0f} days, then only one {coarse} point per {span[coarse]:.0f} days")
    findings.sort(key=lambda f: SEV_ORDER[f["severity"]])
    return {
        "name": cfg.get("name", "backup set"), "today": today.isoformat(), "interval_hours": interval,
        "restore_points": len(kept), "oldest_age_days": round(oldest_days, 1),
        "tiers": tiers, "largest_gaps": sorted(gaps, key=lambda g: -g["gap_days"])[:5],
        "storage_gb": round(gb, 1), "storage_gb_12m": round(gb12, 1),
        "monthly_cost": round(gb * price, 2), "monthly_cost_12m": round(gb12 * price, 2),
        "currency": cfg.get("currency", "USD"), "storage_model": size.get("storage_model", "incremental"),
        "kept": [{"time": t.strftime("%Y-%m-%d %H:%M"), "tiers": tl} for t, tl in kept],
        "findings": findings,
    }


def age_label(d):
    if d < 2:
        return f"{d * 24:.0f} h"
    if d < 60:
        return f"{d:.0f} d"
    if d < 730:
        return f"{d / 30.4:.1f} mo"
    return f"{d / 365:.1f} y"


def render(r):
    out = [f"# Backup retention plan: {r['name']} (as of {r['today']})", "",
           f"Backups every {r['interval_hours']:g} h -> {r['restore_points']} restore points kept, oldest {age_label(r['oldest_age_days'])} old",
           f"Storage ({r['storage_model']}): {r['storage_gb']:.0f} GB now, {r['storage_gb_12m']:.0f} GB in 12 months"
           f" -> {r['monthly_cost']:.2f} -> {r['monthly_cost_12m']:.2f} {r['currency']}/month", "",
           "| Tier | Points | Newest age | Oldest age |", "|---|---|---|---|"]
    for t in r["tiers"]:
        out.append(f"| {t['tier']} | {t['count']} | {age_label(t['newest_age_days'])} | {age_label(t['oldest_age_days'])} |")
    out += ["", "## Largest gaps between restore points", "| Older point | Newer point | Gap | Age of older point |", "|---|---|---|---|"]
    for g in r["largest_gaps"]:
        out.append(f"| {g['from']} | {g['to']} | {g['gap_days']:g} d | {age_label(g['age_days'])} |")
    out += ["", "## Restore points kept"]
    out.append(", ".join(f"{k['time'][:10]} ({'/'.join(x[0].upper() for x in k['tiers'])})" for k in r["kept"]))
    out += ["", "## Findings"]
    if not r["findings"]:
        out.append("- none")
    for f in r["findings"]:
        out.append(f"- {f['severity']} {f['code']}: {f['message']}")
    return "\n".join(out) + "\n"


def self_test():
    ok = 0
    tests = []

    def check(name, cond):
        nonlocal ok
        tests.append(name)
        print(("PASS " if cond else "FAIL ") + name)
        ok += bool(cond)

    today = dt.date(2026, 10, 24)
    base = {"today": "2026-10-24", "backup_interval_hours": 24, "policy": {"daily": 7, "weekly": 4, "monthly": 12},
            "size": {"full_gb": 100, "daily_change_pct": 2}, "requirements": {"rpo_hours": 24, "min_history_days": 35},
            "copies": {"offsite": True, "immutable": True, "encrypted": True}, "last_restore_test": "2026-10-01"}
    r = plan(base, today)
    # daily 7 = 7 newest days; weekly 4 overlaps with dailies; monthly 12
    check("daily 7 + weekly 4 + monthly 12 -> 20 distinct points", r["restore_points"] == 20)
    check("clean policy has no findings", r["findings"] == [])
    check("oldest point is the 2025-11-30 monthly", r["kept"][-1]["time"].startswith("2025-11-30"))
    k = simulate({"daily": 3}, 24, today)
    check("daily 3 keeps 3 newest days", [t.date().day for t, _ in k] == [24, 23, 22])
    k = simulate({"hourly": 6}, 1, today)
    check("hourly 6 keeps 6 points one hour apart", len(k) == 6 and (k[0][0] - k[5][0]) == dt.timedelta(hours=5))
    k = simulate({"weekly": 2}, 24, today)
    check("weekly keeps newest of each ISO week", [t.date().isoformat() for t, _ in k] == ["2026-10-24", "2026-10-18"])
    k = simulate({"monthly": 2}, 24, today)
    check("monthly keeps last day of previous month", [t.date().isoformat() for t, _ in k] == ["2026-10-24", "2026-09-30"])
    k = simulate({"daily": 2, "weekly": 1}, 24, today)
    check("point kept by two tiers stored once", len(k) == 2 and k[0][1] == ["daily", "weekly"])
    k = simulate({"daily": 7}, 12, today)
    check("12 h interval: daily keeps newest per day", len(k) == 7 and [t.hour for t, _ in k[:2]] == [2, 14])
    check("full storage = points x full", storage_gb([(dt.datetime(2026, 1, 2), []), (dt.datetime(2026, 1, 1), [])], {"full_gb": 50, "storage_model": "full"}) == 100)
    check("incremental storage = full + change x days", abs(storage_gb([(dt.datetime(2026, 1, 11), []), (dt.datetime(2026, 1, 1), [])], {"full_gb": 100, "daily_change_pct": 2}) - 120) < 1e-9)
    check("incremental change capped at 100%", storage_gb([(dt.datetime(2026, 6, 1), []), (dt.datetime(2026, 1, 1), [])], {"full_gb": 10, "daily_change_pct": 5}) == 20)

    def codes(**over):
        c = json.loads(json.dumps(base))
        for key, val in over.items():
            if key != "policy" and isinstance(val, dict) and isinstance(c.get(key), dict):
                c[key].update(val)
            else:
                c[key] = val
        return {f["code"] for f in plan(c, today)["findings"]}

    check("RPO missed HIGH", "RPO_MISSED" in codes(requirements={"rpo_hours": 4}))
    check("history short HIGH", "HISTORY_SHORT" in codes(policy={"daily": 14}))
    check("legal retention HIGH", "LEGAL_RETENTION" in codes(requirements={"legal_retention_years": 7}))
    check("yearly 9 satisfies legal 7, yearly 8 does not", "LEGAL_RETENTION" in codes(policy={"daily": 7, "monthly": 12, "yearly": 8}, requirements={"legal_retention_years": 7}) and "LEGAL_RETENTION" not in codes(policy={"daily": 7, "monthly": 12, "yearly": 9}, requirements={"legal_retention_years": 7}))
    check("no offsite HIGH", "NO_OFFSITE" in codes(copies={"offsite": False}))
    check("never restored HIGH", "NEVER_RESTORED" in codes(last_restore_test=None))
    check("restore test old MEDIUM", "RESTORE_TEST_OLD" in codes(last_restore_test="2026-01-01"))
    check("no immutable MEDIUM", "NO_IMMUTABLE" in codes(copies={"immutable": False}))
    check("not encrypted MEDIUM", "NOT_ENCRYPTED" in codes(copies={"encrypted": False}))
    check("overlap HIGH", "OVERLAP" in codes(backup_duration_hours=30))
    check("tight window LOW", "TIGHT_WINDOW" in codes(backup_duration_hours=14))
    check("storage over MEDIUM", "STORAGE_OVER" in codes(requirements={"max_storage_gb": 150}))
    check("tier gap LOW (daily 7 then monthly)", "TIER_GAP" in codes(policy={"daily": 7, "monthly": 12}))
    try:
        plan({"policy": {"daily": 0}}, today)
        check("empty policy rejected", False)
    except DataError:
        check("empty policy rejected", True)
    try:
        plan({"policy": {"fortnightly": 2}}, today)
        check("unknown tier rejected", False)
    except DataError:
        check("unknown tier rejected", True)
    print(f"{ok}/{len(tests)} passed")
    return 0 if ok == len(tests) else 1


def main():
    ap = argparse.ArgumentParser(description="Backup retention (GFS) policy planner")
    ap.add_argument("policy", nargs="?", help="policy JSON file")
    ap.add_argument("--json", action="store_true", help="print JSON instead of Markdown")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args()
    if a.self_test:
        return self_test()
    if not a.policy:
        ap.error("policy file required")
    try:
        with open(a.policy, encoding="utf-8") as fh:
            cfg = json.load(fh)
        r = plan(cfg)
    except (OSError, json.JSONDecodeError, DataError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(r, indent=2) if a.json else render(r), end="" if not a.json else "\n")
    return 1 if any(f["severity"] == "HIGH" for f in r["findings"]) else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: nginx-config-security-reviewer
description: Rà soát tệp nginx.conf và cấu hình các trang web để phát hiện các vấn đề bảo mật như TLS 1.0/1.1, bộ mã hóa (cipher) yếu, thiếu HSTS và các tiêu đề bảo mật (security headers), bẫy kế thừa add_header, lỗi duyệt đường dẫn (path traversal) do lệch dấu gạch chéo trong alias, autoindex, kích thước phần thân yêu cầu (body size) không giới hạn, biến $uri trong chuyển hướng, HTTP không chuyển hướng sang HTTPS, các đường dẫn quản trị bỏ ngỏ và trang đăng nhập không giới hạn tần suất (rate limit). Cung cấp bản cấu hình đã sửa lỗi. Bao gồm công cụ kiểm tra viết bằng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Trình Rà Soát Bảo Mật Cấu Hình Nginx

Bạn rà soát các cấu hình nginx theo đúng cách mà một kỹ sư vận hành (ops engineer) cẩn trọng sẽ làm trước một đợt kiểm toán bảo mật: tìm ra các thiết lập làm lộ dữ liệu hoặc làm suy yếu TLS, giải thích từng vấn đề bằng ngôn từ dễ hiểu, và bàn giao lại một bản cấu hình đã được sửa lỗi nhưng vẫn phục vụ nguyên vẹn các tuyến (routes) như cũ. Bạn tuyệt đối không phỏng đoán về những tệp mà mình chưa được xem, và không bao giờ bảo người dùng nạp lại (reload) cấu hình mà không chạy `nginx -t` trước.

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

- `scripts/nginx_review.py` - phân tích cú pháp các tệp cấu hình nginx thành từng khối (blocks) và in ra các phát hiện kèm theo mức độ nghiêm trọng, số dòng và cách khắc phục (chỉ dùng thư viện chuẩn Python 3)
- `references/hardening-checklist.md` - mọi mục kiểm tra mà kịch bản thực thi, lý do tại sao nó quan trọng và cách khắc phục, cộng thêm các mục cần kiểm tra thủ công
- `references/tls-and-headers.md` - thiết lập giao thức TLS và bộ mã hóa (ciphers), lộ trình triển khai HSTS, các tiêu đề bảo mật và cơ chế hoạt động của tính kế thừa `add_header`
- `templates/review-report.md` - bản báo cáo bạn bàn giao lại: tóm tắt, bảng phát hiện lỗi, phần so sánh khác biệt (diff) của cấu hình, các câu lệnh kiểm tra
- `examples/shop-site.conf` - một cấu hình cửa hàng nhỏ từ năm 2019 với 18 phát hiện lỗi (3 lỗi mức HIGH)
- `examples/shop-site-fixed.conf` - cùng trang web đó sau khi đã áp dụng các bản sửa lỗi (không còn phát hiện lỗi nào ngoại trừ ghi chú về lệnh include)

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

### 1. Thu thập toàn bộ cấu hình
Yêu cầu kết quả đầu ra của lệnh `sudo nginx -T` (lệnh này in ra tệp cấu hình chính và mọi tệp được đính kèm qua lệnh include), hoặc yêu cầu tệp nginx.conf cộng với các tệp liên quan trong thư mục sites-enabled. Hỏi xem trang web đó làm gì (phục vụ tệp tĩnh, reverse proxy, PHP), những đường dẫn nào bắt buộc phải giữ công khai, phiên bản nginx (`nginx -v`) và liệu có CDN hay bộ cân bằng tải (load balancer) nào đứng trước xử lý chấm dứt TLS (terminate TLS) hay không. Nhắc người dùng xóa các khóa bí mật (private keys) hoặc thông tin nhạy cảm (secrets) trước khi dán nội dung vào; giữ nguyên đường dẫn chứng chỉ thì không sao.

### 2. Chạy công cụ kiểm tra
```
python3 scripts/nginx_review.py examples/shop-site.conf
python3 scripts/nginx_review.py /etc/nginx/nginx.conf /etc/nginx/sites-enabled/shop --json
python3 scripts/nginx_review.py --self-test
```
Mã thoát (exit code) 1 có nghĩa là có các phát hiện mức HIGH, 2 có nghĩa là không thể đọc hoặc phân tích cú pháp tệp (thông báo lỗi sẽ chỉ rõ dòng gặp sự cố).

### 3. Xác nhận và bổ sung các bước kiểm tra thủ công
Đọc từng phát hiện lỗi trong mối tương quan với bối cảnh của người dùng: việc có một CDN đứng trước sẽ làm thay đổi các phát hiện về TLS, một tuyến quản trị chỉ dùng nội bộ có thể đã được bảo vệ bởi tường lửa, một câu lệnh `return 404` có thể đã ẩn đường dẫn đó đi rồi. Sau đó, rà soát qua các mục kiểm tra thủ công trong `references/hardening-checklist.md` (các tệp được include, xác minh TLS ở phía upstream, các khối `if`, các bộ xử lý PHP, quyền truy cập tệp). Loại bỏ các cảnh báo dương tính giả (false positives) và giải thích rõ lý do.

### 4. Bàn giao kết quả
Điền vào `templates/review-report.md`: ưu tiên các mục mức HIGH lên đầu, đưa ra bản so sánh khác biệt (diff) tối giản của cấu hình, cùng các bước kiểm thử. Luôn giải thích quy tắc kế thừa của `add_header` bất cứ khi nào lỗi ADD_HEADER_INHERITANCE xuất hiện, bởi vì quy tắc này gây bất ngờ cho hầu hết mọi người. Khi mới bắt đầu áp dụng HSTS cho một trang web chưa từng dùng nó trước đây, hãy đề xuất mức `max-age` ngắn trước.

## Kết quả ví dụ
Đối với `examples/shop-site.conf`: 3 lỗi mức HIGH (bật TLS 1.0/1.1, dùng các bộ mã hóa RC4 và 3DES, khối `location /images` dùng `alias .../images/` cho phép tấn công duyệt đường dẫn qua `/images../`), 6 lỗi mức MEDIUM (kích thước phần thân yêu cầu không giới hạn, cổng 80 trực tiếp trả về nội dung thay vì chuyển hướng, bật autoindex trên `/downloads/`, đường dẫn `/api/` làm mất HSTS và nosniff do tự đặt `add_header` riêng, đường dẫn `/admin/` không được bảo vệ, dùng biến `$uri` trong lệnh chuyển hướng), 8 lỗi mức LOW (server_tokens, các tệp ẩn bắt đầu bằng dấu chấm - dotfiles, thiếu CSP/Referrer-Policy/X-Frame-Options, các tiêu đề proxy, không giới hạn tần suất truy cập trên `/api/auth/login`) và 1 mục mức INFO. Tệp `examples/shop-site-fixed.conf` thể hiện các bản sửa lỗi và vượt qua bước kiểm tra `nginx -t`.

## Quy tắc

- Trích dẫn chính xác dòng bị lỗi và nội dung thay thế chính xác; giữ cho các thay đổi ở mức tối thiểu và bảo toàn nguyên vẹn chức năng định tuyến.
- Luôn kết thúc bằng câu lệnh `sudo nginx -t && sudo systemctl reload nginx` cùng một lệnh kiểm tra bằng curl; tuyệt đối không đề xuất khởi động lại (restart) làm đứt kết nối khi chỉ cần nạp lại (reload) là đủ.
- Không tự bịa ra các chỉ thị (directives): hãy đối chiếu tên chỉ thị với tài liệu chính thức của nginx tương ứng với phiên bản của người dùng (ví dụ: `http2 on;` yêu cầu phiên bản 1.25.1 trở lên, các phiên bản cũ hơn sử dụng `listen 443 ssl http2;`).
- Tuyệt đối không yêu cầu hoặc lặp lại các khóa bí mật (private keys), mật khẩu hoặc mã băm htpasswd.
- Hãy coi việc áp dụng các tiêu đề bảo mật như CSP là một lộ trình triển khai từng bước: đề xuất dùng `Content-Security-Policy-Report-Only` trước đối với các ứng dụng phức tạp.
FILE:references/hardening-checklist.md
# Danh Sách Kiểm Tra Gia Cố Bảo Mật Nginx

Mọi mã lỗi mà kịch bản in ra, lý do tại sao nó quan trọng và cách khắc phục. Mức độ nghiêm trọng dưới đây là mức mặc định; hãy nâng lên hoặc hạ xuống tùy theo bối cảnh thực tế.

## HIGH (Cao)

### OLD_TLS_PROTOCOL
Chỉ thị `ssl_protocols` có liệt kê SSLv3, TLSv1 hoặc TLSv1.1. Các giao thức này đã bị loại bỏ (RFC 8996), không đạt chuẩn PCI DSS và cho phép thực hiện các cuộc tấn công hạ cấp (downgrade attacks). Cách khắc phục: đặt `ssl_protocols TLSv1.2 TLSv1.3;` (đây là giá trị mặc định kể từ phiên bản nginx 1.23.4, vì vậy việc xóa dòng này đi cũng có tác dụng tương tự trên các phiên bản mới). Chỉ những trình khách (clients) quá cũ (như Android 4.3, IE trên Windows 7 chưa cập nhật) mới bị mất quyền truy cập.

### WEAK_CIPHERS
Chỉ thị `ssl_ciphers` cho phép các bộ mã hóa RC4, DES/3DES (lỗ hổng SWEET32), MD5, NULL, EXPORT hoặc ẩn danh (aNULL/ADH). Các mục bắt đầu bằng dấu `!` hoặc `-` là các quy tắc loại trừ nên hoàn toàn hợp lệ. Cách khắc phục: sử dụng danh sách "intermediate" (trung cấp) của Mozilla từ trang ssl-config.mozilla.org hoặc xóa bỏ dòng `ssl_ciphers` để sử dụng cấu hình mặc định của OpenSSL, đồng thời đặt `ssl_prefer_server_ciphers off;` khi chỉ còn lại các bộ mã hóa AEAD hiện đại.

### NO_CERTIFICATE
Một khối server lắng nghe với tham số `ssl` nhưng lại không thiết lập `ssl_certificate` bên trong nó hoặc trong khối http. Khi đó nginx sẽ từ chối khởi động hoặc làm thất bại quá trình bắt tay (handshake). Hãy thêm `ssl_certificate` (chuỗi chứng chỉ đầy đủ - full chain) và `ssl_certificate_key`.

### ALIAS_TRAVERSAL (lệch dấu gạch chéo - off-by-slash)
`location /images { alias /var/www/media/images/; }`: một yêu cầu truy cập tới `/images../secret.txt` sẽ được ánh xạ thành `/var/www/media/images/../secret.txt`, khiến cho các tệp nằm ở thư mục cha ngay phía trên đường dẫn alias có thể bị đọc trái phép (một phát hiện rất phổ biến trong nhiều cuộc kiểm toán bảo mật). Cách khắc phục: đảm bảo cả đường dẫn trong location và đường dẫn trong alias đều kết thúc bằng dấu gạch chéo, tức là `location /images/ { alias /var/www/media/images/; }`, hoặc sử dụng chỉ thị `root` khi đường dẫn URL trùng khớp với tên thư mục trên đĩa.

## MEDIUM (Trung bình)

### HTTP_NO_REDIRECT
Một khối server ở cổng 80 có cùng `server_name` với một khối server HTTPS nhưng lại trực tiếp phục vụ các trang web thay vì chuyển hướng người dùng. Khi đó người dùng và dữ liệu cookie vẫn nằm trên kết nối HTTP thuần không mã hóa. Cách khắc phục:
```
server {
    listen 80;
    server_name shop.example.com;
    location /.well-known/acme-challenge/ { root /var/www/certbot; }
    location / { return 301 https://$host$request_uri; }
}
```

### NO_HSTS
Không có tiêu đề `Strict-Transport-Security` trên máy chủ HTTPS, dẫn đến việc yêu cầu đầu tiên của một phiên truy cập có thể bị tấn công hạ cấp xuống HTTP. Xem tệp `tls-and-headers.md` để biết lộ trình triển khai an toàn.

### ADD_HEADER_INHERITANCE
nginx chỉ kế thừa các chỉ thị `add_header` từ cấp cha khi cấp hiện tại hoàn toàn không có bất kỳ chỉ thị `add_header` nào. Chỉ cần một dòng `add_header Cache-Control no-store;` bên trong khối `location /api/` cũng sẽ làm mất sạch mọi tiêu đề bảo mật được khai báo ở khối `server` đối với location đó. Cách khắc phục: lặp lại đầy đủ các tiêu đề bảo mật bên trong location đó, hoặc tách chúng ra một tệp đoạn mã riêng (`include snippets/security-headers.conf;`) và include tệp này vào mọi khối có sử dụng `add_header` riêng. Trên phiên bản nginx 1.29.3 trở lên, việc đặt `add_header_inherit merge;` trong khối http sẽ giúp các khối con cộng gộp thêm vào các tiêu đề của khối cha thay vì ghi đè toàn bộ. Lưu ý rằng `proxy_set_header`, `fastcgi_param` và `proxy_hide_header` cũng tuân theo đúng quy tắc kế thừa này.

### AUTOINDEX_ON
Tính năng liệt kê thư mục làm hiển thị tên của mọi tệp tin, bao gồm cả các bản sao lưu (backups) và các tệp kết xuất dữ liệu (exports) mà không ai chèn liên kết tới. Hãy tắt tính năng này đi hoặc thiết lập cơ chế bảo vệ cho location đó.

### ADMIN_OPEN
Các đường dẫn như /admin, /phpmyadmin, /actuator, /server-status, /nginx_status hoặc /metrics không được thiết lập quy tắc allow/deny, auth_basic hoặc auth_request. Cách khắc phục: thêm `allow 10.20.0.0/16; deny all;` (dải mạng văn phòng hoặc VPN), hoặc dùng `auth_request` trỏ tới dịch vụ đăng nhập một lần (SSO). Chỉ sử dụng xác thực cơ bản (Basic auth) qua kết nối HTTPS.

### UNLIMITED_BODY
Thiết lập `client_max_body_size 0` sẽ vô hiệu hóa giới hạn kích thước yêu cầu gửi lên, khiến kẻ tấn công dễ dàng làm cạn kiệt dung lượng đĩa và bộ nhớ. Hãy giữ mức mặc định 1m hoặc đặt một mức giới hạn thực tế trong khối http, và chỉ nâng giới hạn này lên ở riêng location dùng để tải tệp lên (upload).

### URI_IN_REDIRECT
Biến `$uri` đã được chuẩn hóa và giải mã URL (URL-decoded), vì vậy chuỗi `%0d%0a` sẽ biến thành ký tự xuống dòng thực sự và kẻ tấn công có thể chèn các tiêu đề (`Set-Cookie`) vào phản hồi chuyển hướng (HTTP response splitting / header injection). Hãy sử dụng biến `$request_uri` (dòng yêu cầu thô, vẫn còn nguyên mã hóa URL) trong các lệnh `return`, đích đến của `rewrite` và `add_header`.

## LOW (Thấp)

### SERVER_TOKENS
Số phiên bản xuất hiện trong tiêu đề `Server` và trên các trang báo lỗi, giúp kẻ tấn công dễ dàng đối chiếu với các lỗ hổng CVE đã biết. Hãy đặt `server_tokens off;` trong khối http.

### MISSING_SECURITY_HEADERS
Trên các máy chủ HTTPS: thiếu `X-Content-Type-Options nosniff`, `X-Frame-Options` (hoặc CSP `frame-ancestors`), `Content-Security-Policy`, `Referrer-Policy`. Hãy thêm chúng kèm theo tham số `always` để các tiêu đề này cũng được gửi đi trong cả các phản hồi lỗi 4xx/5xx.

### SHORT_HSTS
Giá trị `max-age` của HSTS ngắn hơn 180 ngày. Mức này hoàn toàn ổn trong giai đoạn mới triển khai thử nghiệm; hãy nâng nó lên mức một năm sau khi đã chạy ổn định.

### DOTFILES_EXPOSED
Máy chủ phục vụ các tệp tĩnh nhưng lại không có quy tắc chặn các tệp ẩn bắt đầu bằng dấu chấm, dẫn đến việc các tệp như `/.git/config`, `/.env` hoặc `/.htpasswd` có thể bị tải xuống nếu chúng tồn tại bên dưới thư mục gốc của web (web root). Cách khắc phục: thêm `location ~ /\.(?!well-known) { deny all; }` (vẫn giữ cho các yêu cầu xác thực chứng chỉ ACME hoạt động bình thường).

### NO_RATE_LIMIT
Một đường dẫn đăng nhập, xác thực hoặc cấp phát token không được áp dụng `limit_req`. Hãy khai báo một vùng nhớ (zone) trong khối http và áp dụng nó vào location tương ứng; trả về mã lỗi 429 bằng chỉ thị `limit_req_status 429;`.

### PROXY_HEADERS
Một khối location dùng `proxy_pass` nhưng không gửi kèm các tiêu đề Host, X-Forwarded-For và X-Forwarded-Proto, khiến ứng dụng phía sau ghi nhật ký nhầm địa chỉ IP của máy chủ proxy, tạo sai các URL chuyển hướng và có thể hiểu nhầm các yêu cầu HTTPS là HTTP. Hãy nhớ quy tắc kế thừa: chỉ cần một dòng `proxy_set_header` trong khối location cũng sẽ thay thế toàn bộ các dòng `proxy_set_header` được kế thừa từ cấp trên.

## INFO (Thông tin)

### INCLUDE_NOT_FOLLOWED
Kịch bản chỉ đọc những tệp mà bạn truyền trực tiếp vào. Hãy yêu cầu kết quả của lệnh `nginx -T` hoặc các tệp được đính kèm qua lệnh include.

## Kiểm tra thủ công (không tự động hóa)
- `proxy_pass https://...` trỏ tới một máy chủ upstream ngoài internet mà không bật `proxy_ssl_verify on;` và `proxy_ssl_trusted_certificate`.
- PHP: khối `location ~ \.php$` bắt buộc phải sử dụng `try_files $uri =404;` (hoặc `fastcgi_split_path_info` kèm theo bước kiểm tra) để các tệp hình ảnh do người dùng tải lên không thể bị thực thi như mã PHP; các thư mục chứa tệp tải lên tuyệt đối không bao giờ được chuyển tiếp sang bộ xử lý PHP.
- Dùng câu lệnh `if` bên trong khối location với bất kỳ chỉ thị nào khác ngoài `return` hoặc `rewrite ... last` (nguyên tắc nổi tiếng "if is evil").
- Các khối `default_server`: một yêu cầu có tiêu đề Host lạ không xác định nên nhận về `return 444;` kèm chứng chỉ tự ký hoặc bật `ssl_reject_handshake on;` (từ bản 1.19.4 trở lên) thay vì rơi vào trang web đầu tiên trong cấu hình.
- Quyền truy cập tệp (Permissions): các tiến trình worker của nginx không được phép có quyền ghi vào thư mục gốc của web (web root); các khóa bí mật (private keys) phải đặt `chmod 600` và thuộc quyền sở hữu của root.
- Tiêu đề kích thước lớn / các trình khách kết nối chậm (slow clients): cấu hình `client_body_timeout`, `client_header_timeout`, `large_client_header_buffers` cho các API công khai đang chịu tấn công.
- Ghi nhật ký (Logging): nhật ký truy cập (access logs) không được ghi lại các token nằm trong chuỗi truy vấn (query strings); hãy sử dụng một định dạng `log_format` tùy chỉnh nếu cần.
FILE:references/tls-and-headers.md
# TLS và Các Tiêu Đề Bảo Mật

## Thiết lập TLS vượt qua hầu hết các đợt kiểm toán (nginx 1.25+ với OpenSSL 1.1.1 hoặc 3.x)
```
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
```
Đây là cấu hình thuộc hồ sơ "intermediate" (trung cấp) của Mozilla. Các bộ mã hóa của TLS 1.3 không được đặt thông qua chỉ thị `ssl_ciphers` (OpenSSL tự xử lý chúng). Nếu giữ lại các bộ mã hóa DHE, hãy cung cấp thêm `ssl_dhparam` với độ dài tối thiểu 2048 bit hoặc loại bỏ các mục DHE khỏi danh sách.

Tính năng OCSP stapling (`ssl_stapling on; ssl_stapling_verify on;`) là tùy chọn; Let's Encrypt đã ngừng hỗ trợ OCSP vào năm 2025, vì vậy đừng thêm cấu hình này đối với các chứng chỉ của Let's Encrypt.

HTTP/2: dùng `http2 on;` bên trong khối server trên nginx 1.25.1 trở lên; các phiên bản cũ hơn sử dụng `listen 443 ssl http2;`.

## Lộ trình triển khai HSTS
1. Đảm bảo mọi tên miền phụ (subdomain) đều hoạt động tốt qua giao thức HTTPS.
2. Bắt đầu với thời hạn ngắn: `add_header Strict-Transport-Security "max-age=300" always;`
3. Sau một tuần chạy ổn định không phát sinh sự cố: nâng lên `max-age=31536000; includeSubDomains`.
4. Chỉ thêm tham số `preload` và gửi đăng ký lên trang hstspreload.org khi bạn đã hoàn toàn chắc chắn; việc gỡ bỏ khỏi danh sách preload sẽ mất đến hàng tháng trời.
Tiêu đề HSTS gửi trên các phản hồi HTTP thuần sẽ bị trình duyệt bỏ qua, vì vậy hãy đặt nó trên khối server cổng 443.

## Các tiêu đề bảo mật (Security headers)
| Tiêu đề | Giá trị điển hình | Ghi chú |
|---|---|---|
| X-Content-Type-Options | `nosniff` | Ngăn chặn hành vi tự động đoán kiểu MIME đối với các tệp tải lên |
| X-Frame-Options | `DENY` hoặc `SAMEORIGIN` | Chống tấn công Clickjacking; chỉ thị `frame-ancestors` của CSP là giải pháp tương đương hiện đại hơn |
| Content-Security-Policy | `default-src 'self'` và các quy tắc khác | Đặc thù theo từng ứng dụng; hãy triển khai thử nghiệm trước bằng `Content-Security-Policy-Report-Only` |
| Referrer-Policy | `strict-origin-when-cross-origin` | Giữ cho các đường dẫn và chuỗi truy vấn không bị lọt vào nhật ký của các trang web khác |
| Permissions-Policy | `camera=(), microphone=(), geolocation=()` | Tùy chọn |
Hãy thêm tham số `always` để các tiêu đề này luôn được gửi kèm trong cả những phản hồi báo lỗi.

## Quy tắc kế thừa của add_header
```
server {
    add_header X-Content-Type-Options nosniff always;   # A
    location / { }                                      # nhận được A
    location /api/ {
        add_header Cache-Control no-store;              # CHỈ nhận được tiêu đề này, A bị mất
    }
}
```
Một khối chỉ kế thừa các chỉ thị `add_header` từ khối cha của nó nếu bản thân nó không tự định nghĩa bất kỳ chỉ thị `add_header` nào. Hãy gom các tiêu đề dùng chung vào một tệp snippet và include tệp đó vào mọi khối có khai báo thêm tiêu đề riêng. Phiên bản nginx 1.29.3 (tháng 10 năm 2025) đã bổ sung chỉ thị `add_header_inherit merge;`, giúp các khối lồng bên trong cộng gộp thêm vào danh sách tiêu đề được kế thừa; hãy kiểm tra phiên bản bằng `nginx -v` trước khi đề xuất dùng nó (Debian 13 đi kèm bản 1.26).

## Kiểm thử
```
sudo nginx -t && sudo systemctl reload nginx
curl -sI https://shop.example.com/ | grep -iE 'strict|x-content|x-frame|content-security|referrer|server:'
curl -sI http://shop.example.com/page?x=1        # kỳ vọng mã 301 chuyển tới https://shop.example.com/page?x=1
curl -s -o /dev/null -w '%{http_code}\n' https://shop.example.com/.git/config   # kỳ vọng mã 403 hoặc 404
curl -s -o /dev/null -w '%{http_code}\n' https://shop.example.com/images../      # kỳ vọng mã 404 sau khi sửa lỗi alias
openssl s_client -connect shop.example.com:443 -tls1_1 </dev/null   # kỳ vọng quá trình bắt tay thất bại
```
Để kiểm tra toàn diện từ bên ngoài: sử dụng công cụ kiểm tra máy chủ của SSL Labs hoặc chạy `testssl.sh shop.example.com`.
FILE:templates/review-report.md
# Báo cáo rà soát bảo mật Nginx: <tên trang web hoặc máy chủ>

**Phiên bản:** <nginx 1.26.3, OpenSSL 3.x>   **Vai trò:** <trang web tĩnh / reverse proxy trỏ tới Node trên cổng :3000 / PHP-FPM>
**Các tệp đã rà soát:** <đầu ra lệnh nginx -T, 2 tệp>   **TLS được chấm dứt bởi:** <nginx / CDN / bộ cân bằng tải>
**Tóm tắt:** <một câu: vấn đề nghiêm trọng nhất và bản sửa lỗi sẽ thay đổi điều gì>

## Các phát hiện lỗi (Findings)
| # | Mức độ | Mã lỗi | Tệp:dòng | Vấn đề | Cách khắc phục |
|---|---|---|---|---|---|
| 1 | HIGH | <ALIAS_TRAVERSAL> | <nginx.conf:51> | <location /images cho phép truy cập /images../> | <location /images/ { alias .../images/; }> |
| 2 | <MEDIUM> | <...> | <...> | <...> | <...> |

## Các mục giữ nguyên không thay đổi (kèm lý do)
- <ADMIN_OPEN trên /admin/: đã được giới hạn bởi tường lửa đám mây chỉ cho phép mạng VPN; có thêm deny all nữa hay không? có/không>

## Các thay đổi trong cấu hình
```diff
- ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
+ ssl_protocols TLSv1.2 TLSv1.3;
```

## Áp dụng và kiểm thử
1. Sao lưu: `sudo cp -a /etc/nginx /etc/nginx.bak-<ngày>`
2. Chỉnh sửa tệp, sau đó chạy `sudo nginx -t && sudo systemctl reload nginx`
3. Các bước kiểm tra:
   - `curl -sI https://<host>/` hiển thị đầy đủ các tiêu đề bảo mật
   - `curl -sI http://<host>/x?y=1` trả về mã 301 chuyển tới cùng đường dẫn đó trên giao thức https
   - <các lệnh kiểm tra duyệt đường dẫn / tệp ẩn bắt đầu bằng dấu chấm / trang quản trị tương ứng với các phát hiện lỗi>
4. Khôi phục (Roll back): phục hồi lại bản sao lưu và nạp lại (reload) cấu hình.

## Các việc cần theo dõi tiếp (Follow-ups)
- <HSTS: nâng giá trị max-age lên 31536000 sau ngày <ngày>>
- <CSP: chuyển từ chế độ Report-Only sang chế độ bắt buộc thực thi (enforcing) sau khi đã rà soát các báo cáo>
FILE:examples/shop-site.conf
# /etc/nginx/nginx.conf for shop.example.com (single-file setup)
# A small online shop: static storefront, product images, a Node.js API on :3000
# and a legacy admin panel. Written in 2019, certificates renewed by certbot.

user www-data;
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    sendfile on;
    keepalive_timeout 65;
    client_max_body_size 0;

    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers "HIGH:RC4-SHA:DES-CBC3-SHA:!aNULL";
    ssl_prefer_server_ciphers on;

    server {
        listen 80;
        server_name shop.example.com www.shop.example.com;
        root /var/www/shop;

        location /.well-known/acme-challenge/ {
            root /var/www/certbot;
        }
    }

    server {
        listen 443 ssl;
        http2 on;
        server_name shop.example.com www.shop.example.com;

        ssl_certificate /etc/letsencrypt/live/shop.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/shop.example.com/privkey.pem;

        add_header Strict-Transport-Security "max-age=31536000" always;
        add_header X-Content-Type-Options nosniff always;

        root /var/www/shop;
        index index.html;

        location / {
            try_files $uri $uri/ /index.html;
        }

        location /images {
            alias /var/www/shop-media/images/;
        }

        location /downloads/ {
            alias /var/www/shop-media/downloads/;
            autoindex on;
        }

        location /api/ {
            add_header Cache-Control "no-store";
            proxy_pass http://127.0.0.1:3000;
        }

        location /api/auth/login {
            proxy_pass http://127.0.0.1:3000;
            proxy_set_header Host $host;
        }

        location /admin/ {
            proxy_pass http://127.0.0.1:8080/;
        }

        location /old-blog {
            return 301 https://blog.example.com$uri;
        }
    }
}
FILE:examples/shop-site-fixed.conf
# shop.example.com after the review: same routes, hardened.
# Shared security headers live in one snippet so locations with their own
# add_header can include it again (add_header is not inherited into a block
# that sets any add_header of its own).

user www-data;
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    sendfile on;
    keepalive_timeout 65;
    server_tokens off;
    client_max_body_size 10m;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;

    limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;

    server {
        listen 80;
        server_name shop.example.com www.shop.example.com;

        location /.well-known/acme-challenge/ {
            root /var/www/certbot;
        }

        location / {
            return 301 https://$host$request_uri;
        }
    }

    server {
        listen 443 ssl;
        http2 on;
        server_name shop.example.com www.shop.example.com;

        ssl_certificate /etc/letsencrypt/live/shop.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/shop.example.com/privkey.pem;

        # same lines as /etc/nginx/snippets/security-headers.conf
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
        add_header X-Content-Type-Options nosniff always;
        add_header X-Frame-Options SAMEORIGIN always;
        add_header Content-Security-Policy "default-src 'self'; img-src 'self' data:; frame-ancestors 'self'" always;
        add_header Referrer-Policy strict-origin-when-cross-origin always;

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        root /var/www/shop;
        index index.html;

        location ~ /\.(?!well-known) {
            deny all;
        }

        location / {
            try_files $uri $uri/ /index.html;
        }

        location /images/ {
            alias /var/www/shop-media/images/;
        }

        location /downloads/ {
            alias /var/www/shop-media/downloads/;
        }

        location /api/ {
            add_header Cache-Control "no-store" always;
            add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
            add_header X-Content-Type-Options nosniff always;
            add_header X-Frame-Options SAMEORIGIN always;
            add_header Content-Security-Policy "default-src 'self'; img-src 'self' data:; frame-ancestors 'self'" always;
            add_header Referrer-Policy strict-origin-when-cross-origin always;
            proxy_pass http://127.0.0.1:3000;
        }

        location /api/auth/login {
            limit_req zone=login burst=5 nodelay;
            proxy_pass http://127.0.0.1:3000;
        }

        location /admin/ {
            allow 10.20.0.0/16;
            deny all;
            proxy_pass http://127.0.0.1:8080/;
        }

        location /old-blog {
            return 301 https://blog.example.com$request_uri;
        }
    }
}
FILE:scripts/nginx_review.py
#!/usr/bin/env python3
"""Nginx config security reviewer (Python 3 standard library only).

Parses nginx.conf / sites-available files into a block tree and flags common
security and hardening problems: old TLS protocols, weak ciphers, missing HSTS
and security headers, the add_header inheritance trap, alias off-by-slash path
traversal, autoindex, unlimited body size, $uri in redirects (CRLF injection),
plain-HTTP servers without a redirect, open admin paths, login paths without
rate limiting, exposed dotfiles and proxies without forwarding headers.

Usage:
  python3 nginx_review.py site.conf [more.conf ...] [--json]
  python3 nginx_review.py --self-test
Exit codes: 0 = no HIGH findings, 1 = HIGH findings, 2 = unreadable/unparseable input.
"""
import argparse, json, re, sys

SEV_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}
OLD_PROTOCOLS = {"SSLv2", "SSLv3", "TLSv1", "TLSv1.1"}
WEAK_CIPHER_WORDS = ["RC4", "DES", "3DES", "MD5", "NULL", "EXPORT", "EXP-", "aNULL", "eNULL", "ADH", "AECDH"]
SECURITY_HEADERS = {
    "x-content-type-options": "X-Content-Type-Options nosniff",
    "x-frame-options": "X-Frame-Options DENY or SAMEORIGIN (or CSP frame-ancestors)",
    "content-security-policy": "Content-Security-Policy",
    "referrer-policy": "Referrer-Policy strict-origin-when-cross-origin",
}
LOGIN_RE = re.compile(r"login|signin|sign-in|auth|token|password|wp-login", re.I)
ADMIN_RE = re.compile(r"admin|phpmyadmin|actuator|server-status|nginx_status|/metrics|wp-admin", re.I)


class ParseError(Exception):
    pass


class Node:
    def __init__(self, name, args, line, children=None):
        self.name, self.args, self.line, self.children = name, args, line, children

    def get(self, name):
        return [c for c in (self.children or []) if c.name == name]

    def first(self, name):
        found = self.get(name)
        return found[0] if found else None

    def walk(self):
        for c in self.children or []:
            yield c
            if c.children is not None:
                yield from c.walk()


def tokenize(text):
    tokens, i, line, n = [], 0, 1, len(text)
    while i < n:
        ch = text[i]
        if ch == "\n":
            line += 1; i += 1
        elif ch.isspace():
            i += 1
        elif ch == "#":
            while i < n and text[i] != "\n":
                i += 1
        elif ch in "{};":
            tokens.append((ch, line, True)); i += 1
        elif ch in "\"'":
            q, j, buf = ch, i + 1, []
            while j < n and text[j] != q:
                if text[j] == "\\" and j + 1 < n:
                    buf.append(text[j + 1]); j += 2; continue
                if text[j] == "\n":
                    line += 1
                buf.append(text[j]); j += 1
            if j >= n:
                raise ParseError(f"line {line}: unterminated quote")
            tokens.append(("".join(buf), line, False)); i = j + 1
        else:
            j = i
            while j < n and not text[j].isspace() and text[j] not in "{};":
                if text[j] == "$" and j + 1 < n and text[j + 1] == "{":  # var
                    k = text.find("}", j)
                    j = k + 1 if k != -1 else n
                    continue
                j += 1
            tokens.append((text[i:j], line, False)); i = j
    return tokens


def parse(text):
    tokens = tokenize(text)
    root = Node("main", [], 0, [])
    stack, cur = [root], []
    for tok, line, special in tokens:
        if special and tok == ";":
            if not cur:
                continue
            stack[-1].children.append(Node(cur[0][0], [t for t, _ in cur[1:]], cur[0][1]))
            cur = []
        elif special and tok == "{":
            if not cur:
                raise ParseError(f"line {line}: '{{' without a directive name")
            node = Node(cur[0][0], [t for t, _ in cur[1:]], cur[0][1], [])
            stack[-1].children.append(node); stack.append(node); cur = []
        elif special and tok == "}":
            if cur:
                raise ParseError(f"line {line}: missing ';' before '}}'")
            if len(stack) == 1:
                raise ParseError(f"line {line}: unexpected '}}'")
            stack.pop()
        else:
            cur.append((tok, line))
    if cur:
        raise ParseError(f"line {cur[0][1]}: directive '{cur[0][0]}' not terminated with ';'")
    if len(stack) != 1:
        raise ParseError(f"block '{stack[-1].name}' opened on line {stack[-1].line} is not closed")
    return root


def headers_of(node):
    return {d.args[0].lower(): d for d in node.get("add_header") if d.args}


def is_tls(server):
    for l in server.get("listen"):
        if "ssl" in l.args or "quic" in l.args or any(a.endswith(":443") or a == "443" for a in l.args):
            return True
    s = server.first("ssl")
    return bool(s and s.args and s.args[0] == "on")


def listens_plain(server):
    ls = server.get("listen")
    if not ls:
        return True  # default listen *:80
    for l in ls:
        if not ("ssl" in l.args or "quic" in l.args or any(a.endswith(":443") or a == "443" for a in l.args)):
            return True
    return False


def names(server):
    out = []
    for d in server.get("server_name"):
        out.extend(d.args)
    return set(out) or {"_"}


def inherited(scopes, name):
    """Value of a directive as nginx inherits it: innermost scope that sets it."""
    for s in reversed(scopes):
        d = s.first(name)
        if d is not None:
            return d
    return None


def effective_headers(scopes):
    for s in reversed(scopes):
        h = headers_of(s)
        if h:
            return h
    return {}


def review(text, fname="nginx.conf"):
    root = parse(text)
    http = root.first("http")
    top = http if http is not None else root
    base = [root] + ([http] if http is not None else [])
    servers = [s for s in top.get("server")]
    findings = []

    def add(sev, code, line, msg, fix):
        findings.append({"severity": sev, "code": code, "file": fname, "line": line, "message": msg, "fix": fix})

    for d in root.walk():
        if d.name == "include":
            add("INFO", "INCLUDE_NOT_FOLLOWED", d.line, f"include {' '.join(d.args)} is not read by this checker",
                "Review the included files too (pass them as extra arguments) or paste `nginx -T` output.")

    tokens = [d for d in root.walk() if d.name == "server_tokens"]
    if not any(d.args and d.args[0] == "off" for d in tokens):
        add("LOW", "SERVER_TOKENS", (http or root).line, "server_tokens is not off, so error pages and the Server header show the nginx version",
            "Add `server_tokens off;` in the http block.")

    tls_names = set()
    for s in servers:
        if is_tls(s):
            tls_names |= names(s)

    for s in servers:
        scopes = base + [s]
        label = " ".join(sorted(names(s)))
        tls = is_tls(s)
        if tls:
            if inherited(scopes, "ssl_certificate") is None:
                add("HIGH", "NO_CERTIFICATE", s.line, f"TLS server {label} has no ssl_certificate in scope",
                    "Add ssl_certificate and ssl_certificate_key (fullchain + key).")
            proto = inherited(scopes, "ssl_protocols")
            if proto is not None:
                old = [p for p in proto.args if p in OLD_PROTOCOLS]
                if old:
                    add("HIGH", "OLD_TLS_PROTOCOL", proto.line, f"{label}: ssl_protocols enables {', '.join(old)}",
                        "Use `ssl_protocols TLSv1.2 TLSv1.3;` (SSLv3/TLS 1.0/1.1 are deprecated, RFC 8996).")
            ciph = inherited(scopes, "ssl_ciphers")
            if ciph is not None and ciph.args:
                parts = re.split(r"[:\s]+", " ".join(ciph.args))
                weak = sorted({w for p in parts if p and not p.startswith("!") and not p.startswith("-")
                               for w in WEAK_CIPHER_WORDS if w.lower() in p.lower()})
                if weak:
                    add("HIGH", "WEAK_CIPHERS", ciph.line, f"{label}: ssl_ciphers allows weak suites ({', '.join(weak)})",
                        "Use the Mozilla 'intermediate' cipher list, or remove ssl_ciphers to use the safe OpenSSL default.")
            hdrs = effective_headers(scopes)
            if "strict-transport-security" not in hdrs:
                add("MEDIUM", "NO_HSTS", s.line, f"TLS server {label} sends no Strict-Transport-Security header",
                    'Add `add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;` (start with a short max-age).')
            else:
                hsts = hdrs["strict-transport-security"]
                m = re.search(r"max-age=(\d+)", " ".join(hsts.args), re.I)
                if m and int(m.group(1)) < 15552000:
                    add("LOW", "SHORT_HSTS", hsts.line, f"{label}: HSTS max-age {m.group(1)} is under 180 days",
                        "Raise max-age to 31536000 once HTTPS works everywhere.")
            missing = [v for k, v in SECURITY_HEADERS.items() if k not in hdrs]
            if "x-frame-options" not in hdrs and "content-security-policy" in hdrs and \
                    "frame-ancestors" in " ".join(hdrs["content-security-policy"].args):
                missing = [v for v in missing if not v.startswith("X-Frame")]
            if missing:
                add("LOW", "MISSING_SECURITY_HEADERS", s.line, f"{label}: missing {'; '.join(missing)}",
                    "Add them with `always` in the server block (check the inheritance rule for locations).")
        elif listens_plain(s) and names(s) & tls_names:
            redirects = any(r.args and r.args[0] in ("301", "302", "307", "308") and len(r.args) > 1 and r.args[1].startswith("https://")
                            for r in [d for d in s.walk() if d.name == "return"])
            rewrites = any(len(r.args) > 1 and r.args[1].startswith("https://") for r in [d for d in s.walk() if d.name == "rewrite"])
            if not (redirects or rewrites):
                add("MEDIUM", "HTTP_NO_REDIRECT", s.line, f"plain-HTTP server {label} serves content instead of redirecting to HTTPS",
                    "Use `return 301 https://$host$request_uri;` in the port-80 server (keep only /.well-known/acme-challenge/ if needed).")

        server_hdrs = effective_headers(scopes)
        has_dot_rule = False
        locations = [d for d in s.walk() if d.name == "location"]
        for loc in locations:
            path = loc.args[-1] if loc.args else ""
            mod = loc.args[0] if len(loc.args) > 1 else ""
            if mod in ("~", "~*") and (r"/\." in path or path.startswith(r"\.") or r"(^|/)\." in path):
                if loc.get("deny") or any(r.args and r.args[0] in ("403", "404") for r in loc.get("return")):
                    has_dot_rule = True
            own = headers_of(loc)
            hi = inherited(scopes + [loc], "add_header_inherit")
            merge = bool(hi and hi.args and hi.args[0] == "merge")  # nginx 1.29.3+
            if own and server_hdrs and not merge:
                lost = sorted(set(server_hdrs) - set(own))
                if lost:
                    add("MEDIUM", "ADD_HEADER_INHERITANCE", loc.line,
                        f"location {path} has its own add_header, so it silently drops {', '.join(lost)} set at server/http level",
                        "Repeat those headers in this location, include a shared headers snippet, or on nginx 1.29.3+ set `add_header_inherit merge;`.")
            al = loc.first("alias")
            if al and al.args and mod in ("", "^~") and not path.endswith("/") and al.args[0].endswith("/"):
                add("HIGH", "ALIAS_TRAVERSAL", al.line,
                    f"location {path} (no trailing slash) with alias {al.args[0]} (trailing slash) allows {path}../ path traversal",
                    f"Make both end with a slash: `location {path}/ {{ alias {al.args[0]}; }}`.")
            ai = loc.first("autoindex")
            if ai and ai.args and ai.args[0] == "on":
                add("MEDIUM", "AUTOINDEX_ON", ai.line, f"autoindex on in location {path} lists directory contents",
                    "Turn it off, or restrict the location with allow/deny or auth_basic.")
            if ADMIN_RE.search(path):
                guarded = loc.get("deny") or loc.get("auth_basic") or loc.get("auth_request") or loc.get("satisfy") \
                    or any(r.args and r.args[0] in ("403", "404", "444") for r in loc.get("return"))
                if not guarded:
                    add("MEDIUM", "ADMIN_OPEN", loc.line, f"location {path} looks like an admin/status endpoint with no allow/deny or auth",
                        "Add `allow <office/VPN range>; deny all;` or auth_basic/auth_request, or remove the route.")
            if LOGIN_RE.search(path) and not inherited(scopes + [loc], "limit_req"):
                add("LOW", "NO_RATE_LIMIT", loc.line, f"location {path} looks like a login/auth endpoint without limit_req",
                    "Define `limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;` in http and `limit_req zone=login burst=5 nodelay;` here.")
            if loc.first("proxy_pass"):
                ph = set()
                for sc in reversed(scopes + [loc]):  # like add_header: innermost level that sets any wins
                    if sc.get("proxy_set_header"):
                        ph = {d.args[0].lower() for d in sc.get("proxy_set_header") if d.args}
                        break
                miss = [h for h in ("host", "x-forwarded-for", "x-forwarded-proto") if h not in ph]
                if miss:
                    add("LOW", "PROXY_HEADERS", loc.line, f"location {path} proxies without {', '.join(miss)}",
                        "Set proxy_set_header Host $host; X-Forwarded-For $proxy_add_x_forwarded_for; X-Forwarded-Proto $scheme; (note: any proxy_set_header in a location replaces inherited ones).")
        serves_files = inherited(scopes, "root") or any(
            (l.first("root") or l.first("alias")) and not (l.args and l.args[-1].startswith("/.well-known/")) for l in locations)
        if serves_files and not has_dot_rule:
            add("LOW", "DOTFILES_EXPOSED", s.line, f"{label}: no rule blocks hidden files such as /.git/ or /.env",
                r"Add `location ~ /\.(?!well-known) { deny all; }`.")

    for d in root.walk():
        if d.name == "client_max_body_size" and d.args and d.args[0] in ("0", "0m", "0k"):
            add("MEDIUM", "UNLIMITED_BODY", d.line, "client_max_body_size 0 disables the request body limit",
                "Set a real limit (e.g. 10m, or larger only in the upload location).")
        if d.name in ("return", "rewrite", "add_header") and any(re.search(r"\$uri\b|\$document_uri\b", a) for a in d.args):
            add("MEDIUM", "URI_IN_REDIRECT", d.line, f"{d.name} uses $uri (decoded, may contain CR/LF), which allows header injection",
                "Use $request_uri (raw, still encoded) in redirects and headers.")
    findings.sort(key=lambda f: (SEV_ORDER[f["severity"]], f["line"]))
    return {"file": fname, "servers": [{"line": s.line, "names": sorted(names(s)), "tls": is_tls(s)} for s in servers],
            "findings": findings}


def to_markdown(results):
    out = ["# Nginx config security review", ""]
    allf = [f for r in results for f in r["findings"]]
    counts = {k: sum(1 for f in allf if f["severity"] == k) for k in SEV_ORDER}
    out.append("Findings: " + ", ".join(f"{v} {k}" for k, v in counts.items()))
    for r in results:
        out += ["", f"## {r['file']}", "", "| Server | Line | TLS |", "|---|---|---|"]
        for s in r["servers"]:
            out.append(f"| {' '.join(s['names'])} | {s['line']} | {'yes' if s['tls'] else 'no'} |")
        out += ["", "| Severity | Code | Line | Problem | Fix |", "|---|---|---|---|---|"]
        for f in r["findings"]:
            out.append(f"| {f['severity']} | {f['code']} | {f['line']} | {f['message']} | {f['fix']} |")
        if not r["findings"]:
            out.append("| - | - | - | no findings | - |")
    out += ["", "Always run `nginx -t` before reloading, and test with `curl -sI https://<host>/` afterwards."]
    return "\n".join(out)


def self_test():
    results = []

    def check(name, cond):
        results.append(cond)
        print(("PASS " if cond else "FAIL ") + name)

    def codes(conf):
        return [f["code"] for f in review(conf)["findings"]]

    good = """
    http {
      server_tokens off;
      limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;
      server { listen 80; server_name a.test; return 301 https://$host$request_uri; }
      server {
        listen 443 ssl; http2 on; server_name a.test;
        ssl_certificate /c.pem; ssl_certificate_key /k.pem;
        ssl_protocols TLSv1.2 TLSv1.3;
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
        add_header X-Content-Type-Options nosniff always;
        add_header Content-Security-Policy "default-src 'self'; frame-ancestors 'none'" always;
        add_header Referrer-Policy strict-origin-when-cross-origin always;
        root /srv/www;
        location ~ /\\.(?!well-known) { deny all; }
        location /static/ { alias /srv/static/; }
        location /login { limit_req zone=login burst=5 nodelay; proxy_pass http://app;
          proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
          proxy_set_header X-Forwarded-Proto $scheme; }
      }
    }"""
    check("clean config has no findings", codes(good) == [])
    check("comments and quotes parsed", parse('a "b c;" d; # x;\n e f;').children[0].args == ["b c;", "d"])
    check("var token kept", parse("set $x hosta;").children[0].args == ["$x", "hosta"])
    for bad, msg in [("server { listen 80;", "unclosed block"), ("a b", "missing ;"), ("}", "stray brace"), ('a "b;', "unterminated quote")]:
        try:
            parse(bad); check("parse error: " + msg, False)
        except ParseError:
            check("parse error: " + msg, True)
    check("SERVER_TOKENS when missing", "SERVER_TOKENS" in codes("http { server { listen 80; } }"))
    tls = "server { listen 443 ssl; server_name b.test; ssl_certificate /c; %s }"
    check("OLD_TLS_PROTOCOL", "OLD_TLS_PROTOCOL" in codes(tls % "ssl_protocols TLSv1 TLSv1.2;"))
    check("TLSv1.2 alone fine", "OLD_TLS_PROTOCOL" not in codes(tls % "ssl_protocols TLSv1.2;"))
    check("WEAK_CIPHERS", "WEAK_CIPHERS" in codes(tls % "ssl_ciphers 'HIGH:RC4-SHA:DES-CBC3-SHA';"))
    check("excluded !RC4 is fine", "WEAK_CIPHERS" not in codes(tls % "ssl_ciphers 'HIGH:!aNULL:!MD5:!RC4';"))
    check("NO_CERTIFICATE", "NO_CERTIFICATE" in codes("server { listen 443 ssl; }"))
    check("cert inherited from http", "NO_CERTIFICATE" not in codes("http { ssl_certificate /c; server { listen 443 ssl; } }"))
    check("NO_HSTS", "NO_HSTS" in codes(tls % ""))
    check("SHORT_HSTS", "SHORT_HSTS" in codes(tls % 'add_header Strict-Transport-Security "max-age=300";'))
    check("MISSING_SECURITY_HEADERS", "MISSING_SECURITY_HEADERS" in codes(tls % ""))
    inh = tls % 'add_header Strict-Transport-Security "max-age=31536000"; location /api/ { add_header Cache-Control no-store; }'
    r = review(inh)["findings"]
    check("ADD_HEADER_INHERITANCE names lost header",
          any(f["code"] == "ADD_HEADER_INHERITANCE" and "strict-transport-security" in f["message"] for f in r))
    check("headers inherited when location has none", "ADD_HEADER_INHERITANCE" not in codes(
        tls % 'add_header Strict-Transport-Security "max-age=31536000"; location /api/ { proxy_pass http://x; }'))
    check("add_header_inherit merge respected", "ADD_HEADER_INHERITANCE" not in codes(
        tls % 'add_header_inherit merge; add_header Strict-Transport-Security "max-age=31536000"; location /api/ { add_header Cache-Control no-store; }'))
    check("ALIAS_TRAVERSAL", "ALIAS_TRAVERSAL" in codes("server { location /img { alias /srv/img/; } }"))
    check("alias with matching slashes fine", "ALIAS_TRAVERSAL" not in codes("server { location /img/ { alias /srv/img/; } }"))
    check("regex location alias not flagged", "ALIAS_TRAVERSAL" not in codes(r"server { location ~ ^/img/(.*)$ { alias /srv/img/$1; } }"))
    check("AUTOINDEX_ON", "AUTOINDEX_ON" in codes("server { location /files/ { autoindex on; } }"))
    check("HTTP_NO_REDIRECT", "HTTP_NO_REDIRECT" in codes(
        "server { listen 80; server_name c.test; root /x; } server { listen 443 ssl; server_name c.test; ssl_certificate /c; }"))
    check("no HTTP_NO_REDIRECT for unrelated name", "HTTP_NO_REDIRECT" not in codes(
        "server { listen 80; server_name d.test; } server { listen 443 ssl; server_name c.test; ssl_certificate /c; }"))
    check("ADMIN_OPEN", "ADMIN_OPEN" in codes("server { location /admin/ { proxy_pass http://x; } }"))
    check("admin with deny fine", "ADMIN_OPEN" not in codes("server { location /admin/ { allow 10.0.0.0/8; deny all; } }"))
    check("NO_RATE_LIMIT", "NO_RATE_LIMIT" in codes("server { location /api/login { proxy_pass http://x; } }"))
    check("rate limit inherited from server", "NO_RATE_LIMIT" not in codes(
        "server { limit_req zone=z; location /api/login { proxy_pass http://x; } }"))
    check("PROXY_HEADERS", "PROXY_HEADERS" in codes("server { location / { proxy_pass http://x; } }"))
    check("proxy_set_header in location replaces inherited", "PROXY_HEADERS" in codes(
        "server { proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; "
        "proxy_set_header X-Forwarded-Proto $scheme; location / { proxy_set_header Upgrade $http_upgrade; proxy_pass http://x; } }"))
    check("DOTFILES_EXPOSED", "DOTFILES_EXPOSED" in codes("server { root /srv; }"))
    check("ACME-only port 80 server not flagged for dotfiles", "DOTFILES_EXPOSED" not in codes(
        "server { listen 80; location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$host$request_uri; } }"))
    check("UNLIMITED_BODY", "UNLIMITED_BODY" in codes("http { client_max_body_size 0; }"))
    check("URI_IN_REDIRECT", "URI_IN_REDIRECT" in codes("server { return 301 https://$host$uri; }"))
    check("$request_uri fine", "URI_IN_REDIRECT" not in codes("server { return 301 https://$host$request_uri; }"))
    check("INCLUDE_NOT_FOLLOWED", "INCLUDE_NOT_FOLLOWED" in codes("http { include /etc/nginx/conf.d/*.conf; }"))
    check("findings sorted HIGH first", review("server { listen 443 ssl; location /files/ { autoindex on; } }")["findings"][0]["severity"] == "HIGH")
    passed = sum(results)
    print(f"{passed}/{len(results)} passed")
    return 0 if passed == len(results) else 1


def main():
    ap = argparse.ArgumentParser(description="Nginx config security reviewer")
    ap.add_argument("files", nargs="*", help="nginx config files (nginx.conf, sites-available/*, or `nginx -T` output)")
    ap.add_argument("--json", action="store_true", help="print JSON instead of Markdown")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args()
    if a.self_test:
        return self_test()
    if not a.files:
        ap.error("give at least one config file, or --self-test")
    results = []
    for f in a.files:
        try:
            with open(f, encoding="utf-8") as fh:
                results.append(review(fh.read(), f))
        except (OSError, UnicodeDecodeError, ParseError) as e:
            print(f"error: {f}: {e}", file=sys.stderr)
            return 2
    print(json.dumps(results, indent=2) if a.json else to_markdown(results))
    return 1 if any(f["severity"] == "HIGH" for r in results for f in r["findings"]) else 0


if __name__ == "__main__":
    sys.exit(main())