@vnptnan/gate 0.0.0-stage → 1.0.2

package/engine/gate-lib.sh

@@ -0,0 +1,285 @@
+#!/usr/bin/env bash
+# Thư viện dùng chung của Cổng kiểm soát ATBMTT (VNPTNAN_GATE).
+# Chạy được trên Git Bash (Windows), Linux (máy chủ GitLab) và macOS. Chỉ cần: bash >= 4, git, grep -E, awk, sed, wc, stat.
+# Không có đầu vào/đầu ra riêng: gate-scan.sh và các hook gọi các hàm ở đây.
+
+# ---------- Vị trí và cấu hình ----------
+gate_root() {
+  local here
+  here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  echo "${GATE_ROOT:-$(dirname "$here")}"
+}
+
+GATE_ROOT=$(gate_root)
+GATE_VERSION=$(cat "$GATE_ROOT/VERSION" 2>/dev/null || echo "0.0.0")
+GATE_PREFIX="[VNPTNAN_GATE]"
+
+# Giá trị mặc định; ghi đè bằng gate.conf ở gốc bộ công cụ, rồi .vnptnan-gate/gate.conf của dự án, rồi biến môi trường GATE_*.
+GATE_MODE=${GATE_MODE:-}            # enforce | audit
+GATE_DEPS=${GATE_DEPS:-}            # block | warn | off
+GATE_DEPS_AUDIT=${GATE_DEPS_AUDIT:-} # 1 = chạy npm audit / dotnet list --vulnerable (cần mạng, chậm)
+GATE_MAX_COMMITS=${GATE_MAX_COMMITS:-}
+GATE_MAX_FILE=${GATE_MAX_FILE:-}    # bytes; file lớn hơn không quét theo dòng
+GATE_SKIP_PATHS=${GATE_SKIP_PATHS:-}
+GATE_SKIP_EXTRA=${GATE_SKIP_EXTRA:-}   # regex thêm vào SKIP_PATHS mặc định (khoá SKIP_PATHS_EXTRA trong gate.conf)
+GATE_SERVER=${GATE_SERVER:-0}       # 1 khi chạy trong pre-receive của GitLab
+GATE_LOG=${GATE_LOG:-}
+GATE_QUIET=${GATE_QUIET:-0}
+
+gate_load_conf_file() {
+  local f=$1 key val
+  [ -f "$f" ] || return 0
+  while IFS='=' read -r key val || [ -n "$key" ]; do
+    key=$(printf '%s' "$key" | tr -d ' \r')
+    val=$(printf '%s' "$val" | sed 's/[[:space:]]*$//; s/\r$//')
+    case "$key" in
+      ''|'#'*) continue ;;
+      MODE)        [ -z "$GATE_MODE" ] && GATE_MODE=$val ;;
+      DEPS)        [ -z "$GATE_DEPS" ] && GATE_DEPS=$val ;;
+      DEPS_AUDIT)  [ -z "$GATE_DEPS_AUDIT" ] && GATE_DEPS_AUDIT=$val ;;
+      MAX_COMMITS) [ -z "$GATE_MAX_COMMITS" ] && GATE_MAX_COMMITS=$val ;;
+      MAX_FILE)    [ -z "$GATE_MAX_FILE" ] && GATE_MAX_FILE=$val ;;
+      SKIP_PATHS)  [ -z "$GATE_SKIP_PATHS" ] && GATE_SKIP_PATHS=$val ;;
+      SKIP_PATHS_EXTRA) [ -z "$GATE_SKIP_EXTRA" ] && GATE_SKIP_EXTRA=$val ;;
+      LOG)         [ -z "$GATE_LOG" ] && GATE_LOG=$val ;;
+    esac
+  done < "$f"
+}
+
+# Thứ tự ưu tiên: biến môi trường > .vnptnan-gate/gate.conf của dự án > gate.conf của bộ công cụ > mặc định.
+gate_load_conf() {
+  local project_root=${1:-}
+  [ -n "$project_root" ] && gate_load_conf_file "$project_root/.vnptnan-gate/gate.conf"
+  gate_load_conf_file "$GATE_ROOT/gate.conf"
+  : "${GATE_MODE:=enforce}"
+  : "${GATE_DEPS:=warn}"
+  : "${GATE_DEPS_AUDIT:=0}"
+  : "${GATE_MAX_COMMITS:=500}"
+  : "${GATE_MAX_FILE:=5242880}"
+  : "${GATE_SKIP_PATHS:=(^|/)(node_modules|bin|obj|dist|build|out|packages|\.git|vendor|coverage|TestResults)/|\.(min\.js|min\.css|map|lock|snap)$|(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|packages\.lock\.json)$|(^|/)\.vnptnan-gate/}"
+  [ -n "$GATE_SKIP_EXTRA" ] && GATE_SKIP_PATHS="$GATE_SKIP_PATHS|$GATE_SKIP_EXTRA"
+  if [ -z "$GATE_LOG" ]; then
+    if [ "$GATE_SERVER" = "1" ]; then GATE_LOG=/var/log/vnptnan-gate/gate.log
+    elif [ -n "${LOCALAPPDATA:-}" ]; then GATE_LOG="$LOCALAPPDATA/VNPTNAN_GATE/gate.log"
+    else GATE_LOG="$HOME/.vnptnan-gate/gate.log"; fi
+  fi
+}
+
+# ---------- Thông báo ----------
+gate_say() {
+  # Mọi dòng ra stderr. Trong pre-receive, GitLab chỉ hiện dòng có tiền tố GL-HOOK-ERR:.
+  local line
+  for line in "$@"; do
+    if [ "$GATE_SERVER" = "1" ]; then printf 'GL-HOOK-ERR: %s %s\n' "$GATE_PREFIX" "$line" >&2
+    else printf '%s %s\n' "$GATE_PREFIX" "$line" >&2; fi
+  done
+}
+
+# ---------- Nạp rule ----------
+# Mảng song song, chỉ số i: RULE_ID RULE_LEVEL RULE_KIND RULE_RE RULE_MSG
+RULE_ID=(); RULE_LEVEL=(); RULE_KIND=(); RULE_RE=(); RULE_MSG=()
+TEXT_BLOCK=''; TEXT_WARN=''; TEXT_AUDIT=''
+# Ngoại lệ của dự án: ALLOW_ID ALLOW_PATHRE (từ .vnptnan-gate/allow.rules)
+ALLOW_ID=(); ALLOW_PATHRE=()
+
+gate_load_rules() {
+  local file=${1:-$GATE_ROOT/rules/gate.rules} line id level kind re msg
+  [ -f "$file" ] || { gate_say "Không tìm thấy file rule: $file"; return 2; }
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%$'\r'}
+    [ -z "$line" ] && continue
+    case "$line" in
+      '#'*) continue ;;
+      '@block-suffix'*) TEXT_BLOCK=${line#*$'\t'} ; continue ;;
+      '@warn-suffix'*)  TEXT_WARN=${line#*$'\t'} ; continue ;;
+      '@audit-suffix'*) TEXT_AUDIT=${line#*$'\t'} ; continue ;;
+      '@'*) continue ;;
+    esac
+    IFS=$'\t' read -r id level kind re msg <<< "$line"
+    if [ -z "$id" ] || [ -z "$level" ] || [ -z "$kind" ] || [ -z "$re" ]; then
+      gate_say "Dòng rule hỏng (cần 5 cột ngăn bằng TAB): $line"; return 2
+    fi
+    case "$level" in block|warn) ;; *) gate_say "Mức không hợp lệ '$level' ở rule $id"; return 2 ;; esac
+    case "$kind" in line|path|count|size|allow|exempt) ;; *) gate_say "Loại không hợp lệ '$kind' ở rule $id"; return 2 ;; esac
+    RULE_ID+=("$id"); RULE_LEVEL+=("$level"); RULE_KIND+=("$kind"); RULE_RE+=("$re"); RULE_MSG+=("${msg:-}")
+  done < "$file"
+}
+
+gate_load_allow() {
+  # .vnptnan-gate/allow.rules trong repo: rule-id  regex-đường-dẫn  người-duyệt  lý-do
+  local file=$1 line id pathre
+  [ -f "$file" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%$'\r'}
+    [ -z "$line" ] && continue
+    case "$line" in '#'*) continue ;; esac
+    IFS=$'\t' read -r id pathre _ <<< "$line"
+    [ -n "$id" ] && [ -n "$pathre" ] || continue
+    ALLOW_ID+=("$id"); ALLOW_PATHRE+=("$pathre")
+  done < "$file"
+}
+
+gate_is_allowed() {
+  # $1 rule id, $2 path. Đúng khi dự án đã khai ngoại lệ cho rule đó trên đường dẫn đó.
+  local i
+  for i in "${!ALLOW_ID[@]}"; do
+    if [ "${ALLOW_ID[$i]}" = "$1" ] && printf '%s' "$2" | grep -qiE -- "${ALLOW_PATHRE[$i]}"; then return 0; fi
+  done
+  return 1
+}
+
+gate_path_skipped() { printf '%s' "$1" | grep -qiE -- "$GATE_SKIP_PATHS"; }
+
+gate_path_exempt() {
+  local i
+  for i in "${!RULE_ID[@]}"; do
+    [ "${RULE_KIND[$i]}" = exempt ] || continue
+    printf '%s' "$1" | grep -qiE -- "${RULE_RE[$i]}" && return 0
+  done
+  return 1
+}
+
+gate_line_allowed() {
+  # $1 nội dung dòng, $2 id rule đang xét. Đúng khi dòng là giá trị mẫu hoặc có gate-allow:<id>.
+  local i
+  # Ngoại lệ tại dòng chỉ dành cho mã nguồn (có review qua MR); prompt-check.sh tắt bằng GATE_NO_INLINE_ALLOW=1
+  if [ "${GATE_NO_INLINE_ALLOW:-0}" != 1 ]; then
+    printf '%s' "$1" | grep -qiE -- "gate-allow:$2([^a-z0-9-]|$)" && return 0
+  fi
+  for i in "${!RULE_ID[@]}"; do
+    [ "${RULE_KIND[$i]}" = allow ] || continue
+    printf '%s' "$1" | grep -qiE -- "${RULE_RE[$i]}" && return 0
+  done
+  return 1
+}
+
+# ---------- Che giá trị nhạy cảm khi in và ghi log ----------
+gate_mask() {
+  # In tối đa 72 ký tự của dòng, phần khớp regex được thay bằng 6 ký tự đầu + ***.
+  local text=$1 re=$2 m masked
+  m=$(printf '%s' "$text" | grep -oiE -- "$re" | head -n1)
+  if [ -n "$m" ] && [ ${#m} -gt 8 ]; then
+    masked=${text//"$m"/${m:0:6}***}
+  else
+    masked=$text
+  fi
+  masked=$(printf '%s' "$masked" | sed 's/^[[:space:]]*//')
+  [ ${#masked} -gt 72 ] && masked="${masked:0:72}..."
+  printf '%s' "$masked"
+}
+
+# ---------- Ghi log ----------
+gate_log() {
+  # stage level id decision path lineno masked
+  local dir
+  dir=$(dirname "$GATE_LOG")
+  mkdir -p "$dir" 2>/dev/null || return 0
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$GATE_VERSION" "$GATE_MODE" "$1" "$2" "$3" "$4" "${GATE_REPO_NAME:-?}" "$5" "$6" "$7" >> "$GATE_LOG" 2>/dev/null || true
+}
+
+# ---------- Kết quả ----------
+GATE_N_BLOCK=0; GATE_N_WARN=0; GATE_N_ALLOWED=0
+GATE_STAGE=${GATE_STAGE:-scan}
+GATE_REPO_NAME=${GATE_REPO_NAME:-}
+
+gate_report_finding() {
+  # $1 level, $2 id, $3 path, $4 lineno, $5 masked text, $6 message
+  local level=$1 id=$2 path=$3 ln=$4 masked=$5 msg=$6 decision tag
+  if gate_is_allowed "$id" "$path"; then
+    GATE_N_ALLOWED=$((GATE_N_ALLOWED + 1))
+    gate_log "$GATE_STAGE" "$level" "$id" allowed "${GATE_PATH_PREFIX:-}$path" "$ln" "$masked"
+    return 0
+  fi
+  if [ "$level" = block ] && [ "$GATE_MODE" != audit ]; then
+    GATE_N_BLOCK=$((GATE_N_BLOCK + 1)); decision=block; tag=CHAN
+  elif [ "$level" = block ]; then
+    GATE_N_WARN=$((GATE_N_WARN + 1)); decision=audit; tag=AUDIT
+  else
+    GATE_N_WARN=$((GATE_N_WARN + 1)); decision=warn; tag=CANH-BAO
+  fi
+  gate_log "$GATE_STAGE" "$level" "$id" "$decision" "${GATE_PATH_PREFIX:-}$path" "$ln" "$masked"
+  if [ -n "$ln" ]; then gate_say "$tag $id  ${GATE_PATH_PREFIX:-}$path:$ln  $msg"
+  else gate_say "$tag $id  ${GATE_PATH_PREFIX:-}$path  $msg"; fi
+  [ -n "$masked" ] && [ "$GATE_QUIET" != 1 ] && gate_say "    > $masked"
+  return 0
+}
+
+# ---------- Quét một file ----------
+# gate_scan_file <path> <file-chứa-các-dòng-cần-quét> [file-đầy-đủ] [kích-thước-bytes]
+#   file-chứa-các-dòng: các dòng được thêm (diff) hoặc toàn bộ nội dung (quét cả cây); đã bỏ dấu + ở đầu.
+#   file-đầy-đủ: nội dung đầy đủ để kiểm rule count/size; bỏ trống thì dùng file-chứa-các-dòng.
+gate_scan_file() {
+  local path=$1 lines=$2 full=${3:-$2} size=${4:-} i id level kind re msg hit ln text masked n thr
+  gate_path_skipped "$path" && return 0
+
+  # Rule đường dẫn
+  if ! gate_path_exempt "$path"; then
+    for i in "${!RULE_ID[@]}"; do
+      [ "${RULE_KIND[$i]}" = path ] || continue
+      if printf '%s' "$path" | grep -qiE -- "${RULE_RE[$i]}"; then
+        gate_report_finding "${RULE_LEVEL[$i]}" "${RULE_ID[$i]}" "$path" "" "" "${RULE_MSG[$i]}"
+      fi
+    done
+  fi
+
+  [ -s "$lines" ] || return 0
+  # File nhị phân: không quét theo dòng.
+  if grep -qI . "$lines" 2>/dev/null; then :; else return 0; fi
+  if [ -z "$size" ]; then size=$(wc -c < "$full" | tr -d ' '); fi
+
+  # Rule kích thước
+  for i in "${!RULE_ID[@]}"; do
+    [ "${RULE_KIND[$i]}" = size ] || continue
+    thr=${RULE_RE[$i]%%|*}; re=${RULE_RE[$i]#*|}
+    if [ "$size" -gt "$thr" ] && printf '%s' "$path" | grep -qiE -- "$re"; then
+      gate_report_finding "${RULE_LEVEL[$i]}" "${RULE_ID[$i]}" "$path" "" "$size bytes" "${RULE_MSG[$i]}"
+    fi
+  done
+
+  [ "$size" -gt "$GATE_MAX_FILE" ] && return 0
+
+  # Rule đếm (trên nội dung đầy đủ)
+  for i in "${!RULE_ID[@]}"; do
+    [ "${RULE_KIND[$i]}" = count ] || continue
+    thr=${RULE_RE[$i]%%|*}; re=${RULE_RE[$i]#*|}
+    n=$(grep -ciE -- "$re" "$full" 2>/dev/null || true); n=${n:-0}
+    if [ "$n" -ge "$thr" ]; then
+      gate_report_finding "${RULE_LEVEL[$i]}" "${RULE_ID[$i]}" "$path" "" "$n dòng khớp (ngưỡng $thr)" "${RULE_MSG[$i]}"
+    fi
+  done
+
+  # Rule theo dòng (trên các dòng được thêm)
+  for i in "${!RULE_ID[@]}"; do
+    [ "${RULE_KIND[$i]}" = line ] || continue
+    id=${RULE_ID[$i]}; level=${RULE_LEVEL[$i]}; re=${RULE_RE[$i]}; msg=${RULE_MSG[$i]}
+    while IFS= read -r hit; do
+      [ -n "$hit" ] || continue
+      ln=${hit%%:*}; text=${hit#*:}
+      if gate_line_allowed "$text" "$id"; then
+        GATE_N_ALLOWED=$((GATE_N_ALLOWED + 1))
+        gate_log "$GATE_STAGE" "$level" "$id" allowed-inline "$path" "$ln" "$(gate_mask "$text" "$re")"
+        continue
+      fi
+      masked=$(gate_mask "$text" "$re")
+      gate_report_finding "$level" "$id" "$path" "$ln" "$masked" "$msg"
+    done < <(grep -niE -- "$re" "$lines" 2>/dev/null | head -n 20)
+  done
+}
+
+gate_summary() {
+  # Trả về mã thoát: 1 nếu phải chặn, 0 nếu không.
+  local what=${1:-thay đổi}
+  if [ "$GATE_N_BLOCK" -gt 0 ]; then
+    gate_say "Từ chối $what: $GATE_N_BLOCK vi phạm mức CHẶN, $GATE_N_WARN cảnh báo, $GATE_N_ALLOWED ngoại lệ đã khai."
+    gate_say "$TEXT_BLOCK"
+    return 1
+  fi
+  if [ "$GATE_N_WARN" -gt 0 ]; then
+    if [ "$GATE_MODE" = audit ]; then gate_say "Chế độ audit: $GATE_N_WARN phát hiện, đã ghi log, cho qua. $TEXT_AUDIT"
+    else gate_say "Cho qua với $GATE_N_WARN cảnh báo, $GATE_N_ALLOWED ngoại lệ đã khai. $TEXT_WARN"; fi
+    return 0
+  fi
+  [ "$GATE_QUIET" = 1 ] || gate_say "Đạt: không phát hiện vi phạm ($GATE_N_ALLOWED ngoại lệ đã khai)."
+  return 0
+}

package/engine/gate-scan.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Điểm vào của Cổng kiểm soát ATBMTT (VNPTNAN_GATE).
+#
+#   gate-scan.sh staged                 # quét thay đổi đã stage (pre-commit)
+#   gate-scan.sh range <old> <new>      # quét các commit trong khoảng (pre-push); <old> có thể là 0000... (nhánh mới)
+#   gate-scan.sh receive                # đọc "old new ref" từ stdin (pre-push và pre-receive của GitLab)
+#   gate-scan.sh commit <sha>           # quét một commit
+#   gate-scan.sh tree [thư-mục]         # quét toàn bộ cây làm việc (đánh giá repo cũ, CI)
+#   gate-scan.sh deps [thư-mục]         # kiểm dependency và giấy phép
+#
+# Mã thoát: 0 cho qua, 1 từ chối, 2 lỗi cấu hình.
+set -u
+ENGINE_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=gate-lib.sh
+. "$ENGINE_DIR/gate-lib.sh"
+
+mode=${1:-}
+shift || true
+
+ZERO='^0+$'
+TMP=$(mktemp -d 2>/dev/null || mktemp -d -t gate)
+trap 'rm -rf "$TMP"' EXIT
+
+repo_root() { git rev-parse --show-toplevel 2>/dev/null || pwd; }
+
+init() {
+  local root
+  root=$(repo_root)
+  GATE_REPO_NAME=${GL_PROJECT_PATH:-$(basename "$root")}
+  gate_load_conf "$root"
+  gate_load_rules || exit 2
+  gate_load_allow "$root/.vnptnan-gate/allow.rules"
+  # Trên server, file ngoại lệ nằm trong commit mới, đọc từ nhánh được đẩy nếu có.
+  if [ "$GATE_SERVER" = 1 ] && [ -n "${GATE_ALLOW_REV:-}" ]; then
+    if git cat-file -e "$GATE_ALLOW_REV:.vnptnan-gate/allow.rules" 2>/dev/null; then
+      git show "$GATE_ALLOW_REV:.vnptnan-gate/allow.rules" > "$TMP/allow.rules" && gate_load_allow "$TMP/allow.rules"
+    fi
+  fi
+}
+
+# Các dòng được thêm của một diff, bỏ dấu +, bỏ \r. $1 ... là đối số cho git diff.
+added_lines() {
+  git diff --no-color --no-ext-diff -U0 --diff-filter=ACMR "$@" 2>/dev/null \
+    | grep -E '^\+' | grep -vE '^\+\+\+ ' | sed 's/^+//; s/\r$//'
+}
+
+scan_staged() {
+  GATE_STAGE=pre-commit
+  local path blob
+  while IFS= read -r -d '' path; do
+    [ -n "$path" ] || continue
+    added_lines --cached -- "$path" > "$TMP/lines"
+    git show ":$path" > "$TMP/full" 2>/dev/null || : > "$TMP/full"
+    gate_scan_file "$path" "$TMP/lines" "$TMP/full"
+  done < <(git diff --cached --name-only --diff-filter=ACMR -z)
+}
+
+scan_commit() {
+  # $1 sha. Commit merge chỉ quét những dòng merge tự thêm (so với cha đầu tiên).
+  local sha=$1 path short
+  short=$(git rev-parse --short "$sha" 2>/dev/null || echo "$sha")
+  while IFS= read -r -d '' path; do
+    [ -n "$path" ] || continue
+    printf '%s' "$path" | grep -qiE '(^|/)(package\.json|[^/]+\.csproj|Directory\.Packages\.props|packages\.config)$' && DEPS_TOUCHED=1
+    git diff --no-color --no-ext-diff -U0 --diff-filter=ACMR "$sha^" "$sha" -- "$path" 2>/dev/null \
+      | grep -E '^\+' | grep -vE '^\+\+\+ ' | sed 's/^+//; s/\r$//' > "$TMP/lines"
+    if ! git rev-parse -q --verify "$sha^" >/dev/null 2>&1; then
+      # Commit gốc: mọi dòng đều là dòng thêm.
+      git show "$sha:$path" 2>/dev/null | sed 's/\r$//' > "$TMP/lines"
+    fi
+    git show "$sha:$path" > "$TMP/full" 2>/dev/null || : > "$TMP/full"
+    GATE_PATH_PREFIX="$short:" gate_scan_file "$path" "$TMP/lines" "$TMP/full"
+  done < <(git diff-tree -r -z --no-commit-id --name-only --diff-filter=ACMR --root "$sha" 2>/dev/null)
+}
+
+scan_range() {
+  # $1 old, $2 new, $3 ref (tuỳ chọn)
+  local old=$1 new=$2 ref=${3:-} list n=0
+  if printf '%s' "$new" | grep -qE "$ZERO"; then return 0; fi   # xoá nhánh: không có gì để quét
+  if printf '%s' "$old" | grep -qE "$ZERO"; then
+    # Nhánh mới: chỉ các commit chưa có ở bất kỳ ref nào khác.
+    if [ "$GATE_SERVER" = 1 ]; then list=$(git rev-list "$new" --not --all 2>/dev/null)
+    else list=$(git rev-list "$new" --not --remotes 2>/dev/null); fi
+  else
+    list=$(git rev-list "$old..$new" 2>/dev/null)
+  fi
+  [ -n "$list" ] || return 0
+  n=$(printf '%s\n' "$list" | wc -l | tr -d ' ')
+  if [ "$n" -gt "$GATE_MAX_COMMITS" ]; then
+    gate_say "Khoảng đẩy có $n commit, chỉ quét $GATE_MAX_COMMITS commit mới nhất (MAX_COMMITS). Phần còn lại cần quét bằng: vnptnan-gate scan tree"
+    list=$(printf '%s\n' "$list" | head -n "$GATE_MAX_COMMITS")
+  fi
+  [ -n "$ref" ] && [ "$GATE_QUIET" != 1 ] && gate_say "Quét $n commit lên $ref"
+  GATE_ALLOW_REV=$new
+  while IFS= read -r sha; do [ -n "$sha" ] && scan_commit "$sha"; done <<< "$list"
+  # Dependency: chỉ trên máy dev (server không có node_modules/NuGet cache) và chỉ khi khoảng đẩy có đổi file khai báo package.
+  if [ "$GATE_DEPS" != off ] && [ "$GATE_SERVER" != 1 ] && [ "${DEPS_TOUCHED:-0}" = 1 ]; then
+    deps_check "$(repo_root)"
+  fi
+}
+
+scan_receive() {
+  local old new ref
+  GATE_STAGE=${GATE_STAGE_NAME:-pre-push}
+  [ "$GATE_SERVER" = 1 ] && GATE_STAGE=pre-receive
+  local a b c d
+  while read -r a b c d; do
+    [ -n "$c" ] || continue
+    if [ -n "$d" ]; then
+      # pre-push của git: local_ref local_sha remote_ref remote_sha
+      scan_range "$d" "$b" "$c"
+    else
+      # pre-receive của GitLab: old new ref
+      scan_range "$a" "$b" "$c"
+    fi
+  done
+}
+
+scan_tree() {
+  local dir=${1:-.} f rel size
+  GATE_STAGE=tree
+  dir=$(cd "$dir" && pwd)
+  if git -C "$dir" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    # File git theo dõi + file chưa theo dõi nhưng không bị ignore.
+    git -C "$dir" ls-files -z --cached --others --exclude-standard
+  else
+    find "$dir" -type f -print0
+  fi > "$TMP/files"
+  while IFS= read -r -d '' f; do
+    [ -n "$f" ] || continue
+    rel=${f#"$dir"/}
+    [ -f "$dir/$rel" ] || continue
+    size=$(wc -c < "$dir/$rel" | tr -d ' ')
+    sed 's/\r$//' "$dir/$rel" > "$TMP/lines" 2>/dev/null || continue
+    gate_scan_file "$rel" "$TMP/lines" "$TMP/lines" "$size"
+  done < "$TMP/files"
+  [ "$GATE_DEPS" != off ] && deps_check "$dir"
+}
+
+deps_check() {
+  # shellcheck source=gate-deps.sh
+  . "$ENGINE_DIR/gate-deps.sh"
+  gate_deps_scan "$1"
+}
+
+case "$mode" in
+  staged)  init; scan_staged; gate_summary "commit" ;;
+  range)   init; GATE_STAGE=pre-push; scan_range "${1:?old}" "${2:?new}" "${3:-}"; gate_summary "push" ;;
+  receive) init; scan_receive; gate_summary "push" ;;
+  commit)  init; GATE_STAGE=commit; scan_commit "${1:?sha}"; gate_summary "commit" ;;
+  tree)    init; scan_tree "${1:-.}"; gate_summary "cây làm việc" ;;
+  deps)    init; GATE_STAGE=deps; deps_check "${1:-$(repo_root)}"; gate_summary "dependency" ;;
+  version) echo "VNPTNAN_GATE $GATE_VERSION" ;;
+  *) echo "Cách dùng: gate-scan.sh staged | range <old> <new> | receive | commit <sha> | tree [dir] | deps [dir]" >&2; exit 2 ;;
+esac

package/engine/prompt-check.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Kiểm tra prompt TRƯỚC KHI gửi tới mô hình — hook UserPromptSubmit của Claude Code và Codex.
+# Dùng chung rule với cổng commit (rules/gate.rules): rule kind=line và kind=count áp lên nội dung prompt.
+#
+#   stdin : JSON của sự kiện UserPromptSubmit (có trường "prompt")
+#   stdout: {"decision":"block","reason":"..."} khi phải chặn (Claude Code và Codex cùng hiểu); rỗng khi cho qua
+#   Mã thoát luôn 0: hook lỗi thì cho qua (cùng cách Codex xử lý), lần lỗi được ghi log.
+#
+#   bash prompt-check.sh --agent claude|codex
+#
+# Khác với cổng commit, ở đây KHÔNG áp dụng ngoại lệ: không đọc .vnptnan-gate/allow.rules và không nhận
+# "gate-allow:" trong prompt, vì prompt không qua merge request nên không có ai duyệt ngoại lệ.
+# Antigravity không có sự kiện trước khi gửi prompt có quyền chặn, nên không dùng được script này.
+
+# Không tin biến môi trường: chỉ đọc gate.conf ở thư mục cài (chỉ admin ghi được)
+unset VNPTNAN_GATE_HOME GATE_ROOT GATE_MODE GATE_DEPS GATE_DEPS_AUDIT GATE_SKIP_PATHS GATE_SKIP_EXTRA \
+      GATE_MAX_COMMITS GATE_MAX_FILE GATE_QUIET GATE_SERVER
+set -u
+ENGINE_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+AGENT=claude
+[ "${1:-}" = "--agent" ] && AGENT=${2:-claude}
+
+TMP=$(mktemp -d 2>/dev/null || mktemp -d -t gateprompt)
+trap 'rm -rf "$TMP"' EXIT
+cat > "$TMP/in.json"
+
+# Lấy trường "prompt" và giải mã chuỗi JSON (\n, \", \\, \uXXXX kể cả cặp surrogate) bằng perl có sẵn trong Git for Windows,
+# không cần module ngoài. Không có trường prompt thì cho qua.
+perl -e '
+  local $/; my $j = <STDIN>;
+  exit 3 unless $j =~ /"prompt"\s*:\s*"((?:[^"\\]|\\.)*)"/s;
+  my $s = $1; my $out = "";
+  while ($s =~ /\G(?:([^\\]+)|\\u([0-9a-fA-F]{4})(?:\\u([0-9a-fA-F]{4}))?|\\(.))/gcs) {
+    if (defined $1) { $out .= $1; next }
+    if (defined $2) {
+      my $c = hex $2;
+      if ($c >= 0xD800 && $c <= 0xDBFF && defined $3) { $c = 0x10000 + (($c - 0xD800) << 10) + (hex($3) - 0xDC00) }
+      elsif (defined $3) { $out .= chr_utf8($c); $c = hex $3 }
+      $out .= chr_utf8($c); next
+    }
+    my %m = (n => "\n", t => "\t", r => "", b => "", f => "", "/" => "/", "\\" => "\\", "\"" => "\"");
+    $out .= exists $m{$4} ? $m{$4} : $4;
+  }
+  sub chr_utf8 { my $c = shift; my $x = chr($c); utf8::encode($x); return $x }
+  print $out;
+' < "$TMP/in.json" > "$TMP/prompt.txt" 2>/dev/null
+rc=$?
+[ "$rc" -eq 3 ] && exit 0
+if [ "$rc" -ne 0 ]; then
+  echo "[VNPTNAN_GATE] prompt-check: không đọc được JSON đầu vào, cho qua" >&2
+  exit 0
+fi
+[ -s "$TMP/prompt.txt" ] || exit 0
+
+# shellcheck source=gate-lib.sh
+. "$ENGINE_DIR/gate-lib.sh"
+gate_load_conf ""
+gate_load_rules >/dev/null 2>&1 || { echo "[VNPTNAN_GATE] prompt-check: không nạp được rule, cho qua" >&2; exit 0; }
+GATE_STAGE="prompt-$AGENT"
+GATE_REPO_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
+GATE_QUIET=1
+GATE_NO_INLINE_ALLOW=1   # gate-lib: bỏ qua "gate-allow:" trên dòng
+GATE_SKIP_PATHS='^$'     # không bỏ qua gì: đường dẫn giả "<prompt>" phải được quét
+
+# Quét; thu các dòng thông báo để làm lý do chặn
+gate_scan_file "<prompt>" "$TMP/prompt.txt" "$TMP/prompt.txt" "$(wc -c < "$TMP/prompt.txt" | tr -d ' ')" 2> "$TMP/findings.txt"
+
+if [ "$GATE_N_BLOCK" -gt 0 ]; then
+  {
+    echo "Cổng kiểm soát ATBMTT đã chặn prompt này trước khi gửi tới AI (Bộ quy tắc sử dụng AI, Điều 5: dữ liệu mức C3 không được đưa vào AI)."
+    sed -n 's/^\[VNPTNAN_GATE\] CHAN \([a-z0-9-]*\)  <prompt>\(:[0-9]*\)\{0,1\}  /- \1: /p' "$TMP/findings.txt" | head -n 8
+    echo "Gỡ mật khẩu, khoá, dữ liệu khách hàng khỏi prompt (thay bằng biến môi trường, dữ liệu giả hoặc mô tả bằng lời) rồi gửi lại."
+  } > "$TMP/reason.txt"
+  perl -e 'local $/; my $r = <STDIN>; $r =~ s/\\/\\\\/g; $r =~ s/"/\\"/g; $r =~ s/\r//g; $r =~ s/\n/\\n/g; $r =~ s/\t/\\t/g;
+           print "{\"decision\":\"block\",\"reason\":\"$r\"}\n"' < "$TMP/reason.txt"
+fi
+exit 0

package/gate.conf

@@ -0,0 +1,13 @@
+# Cấu hình cấp bộ công cụ. Dự án ghi đè bằng .vnptnan-gate/gate.conf; biến môi trường GATE_* ghi đè tất cả.
+# MODE: enforce (từ chối commit/push vi phạm mức block) | audit (chỉ ghi log; dùng trong 2 tuần thí điểm)
+MODE=enforce
+# DEPS: block | warn | off  — mức tối đa cho phát hiện về dependency/giấy phép
+DEPS=warn
+# DEPS_AUDIT: 1 = chạy npm audit / dotnet list package --vulnerable (cần mạng, chậm); mặc định tắt trong hook, bật trong CI
+DEPS_AUDIT=0
+# Số commit tối đa quét trong một lần push
+MAX_COMMITS=500
+# File lớn hơn (bytes) không quét theo dòng
+MAX_FILE=5242880
+# SKIP_PATHS_EXTRA: regex đường dẫn thêm vào danh sách bỏ qua mặc định (thường đặt trong .vnptnan-gate/gate.conf của dự án)
+#SKIP_PATHS_EXTRA=(^|/)legacy-dump/

package/hooks/commit-msg

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Hook commit-msg của VNPTNAN_GATE: ghi vết commit có AI tham gia để thống kê và kiểm toán.
+# Nếu thông điệp có trailer Co-Authored-By của một coding agent mà chưa có trailer AI-Assisted, tự thêm "AI-Assisted: <tool>".
+# Không bao giờ từ chối commit.
+msg=$1
+[ -f "$msg" ] || exit 0
+if grep -qiE '^AI-Assisted:' "$msg"; then exit 0; fi
+tool=$(grep -iE '^Co-Authored-By:.*(claude|codex|openai|antigravity|gemini|copilot)' "$msg" | head -n1 | sed -E 's/^Co-Authored-By:[[:space:]]*//I; s/[[:space:]]*<.*//')
+if [ -n "$tool" ]; then printf '\nAI-Assisted: %s\n' "$tool" >> "$msg"; fi
+exit 0

package/hooks/pre-commit

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Hook pre-commit của VNPTNAN_GATE: quét thay đổi đã stage trước khi commit.
+# Cài qua git config hook.vnptnan-gate-commit.* (cấp máy) hoặc copy vào .git/hooks/pre-commit của repo.
+# Chống hạ cổng bằng biến môi trường (vd. GATE_MODE=audit git commit): hook chỉ tin gate.conf.
+unset VNPTNAN_GATE_HOME GATE_ROOT GATE_MODE GATE_DEPS GATE_DEPS_AUDIT GATE_SKIP_PATHS GATE_SKIP_EXTRA GATE_MAX_COMMITS GATE_MAX_FILE GATE_QUIET GATE_SERVER
+root=$(cd "$(dirname "$0")/.." && pwd)
+GATE_STAGE_NAME=pre-commit exec bash "$root/engine/gate-scan.sh" staged

package/hooks/pre-push

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Hook pre-push của VNPTNAN_GATE: quét mọi commit sắp rời máy, kể cả commit tri thức của VNPTNAN_HARNESS (dùng lệnh plumbing, không qua pre-commit).
+# stdin: <local ref> <local sha> <remote ref> <remote sha>, một dòng mỗi ref.
+# Chống hạ cổng bằng biến môi trường (vd. GATE_MODE=audit git commit): hook chỉ tin gate.conf.
+unset VNPTNAN_GATE_HOME GATE_ROOT GATE_MODE GATE_DEPS GATE_DEPS_AUDIT GATE_SKIP_PATHS GATE_SKIP_EXTRA GATE_MAX_COMMITS GATE_MAX_FILE GATE_QUIET GATE_SERVER
+root=$(cd "$(dirname "$0")/.." && pwd)
+GATE_STAGE_NAME=pre-push exec bash "$root/engine/gate-scan.sh" receive

package/installer/install-server.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Cài VNPTNAN_GATE làm server hook toàn cục trên máy chủ GitLab tự host (Linux package / Omnibus, mọi bậc kể cả Free).
+# Chạy bằng root trên máy chủ GitLab:
+#   sudo bash installer/install-server.sh [-mode enforce|audit]
+# Việc làm: copy bộ công cụ vào /opt/vnptnan-gate (root sở hữu, git chỉ đọc), tạo thư mục custom_hooks/pre-receive.d,
+# đặt symlink 10-vnptnan-gate, tạo /var/log/vnptnan-gate cho tài khoản git ghi. Không cần khởi động lại GitLab.
+# Tài liệu GitLab: Administration > Git server hooks (thư mục custom_hooks toàn cục: gitaly['configuration'][:hooks][:custom_hooks_dir],
+# mặc định /var/opt/gitlab/gitaly/custom_hooks).
+set -eu
+MODE=enforce
+[ "${1:-}" = "-mode" ] && MODE=${2:-enforce}
+SRC=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+DEST=/opt/vnptnan-gate
+HOOKS_DIR=${GITLAB_CUSTOM_HOOKS_DIR:-/var/opt/gitlab/gitaly/custom_hooks}
+GIT_USER=${GITLAB_GIT_USER:-git}
+
+[ "$(id -u)" = 0 ] || { echo "Chạy bằng root."; exit 2; }
+id "$GIT_USER" >/dev/null 2>&1 || { echo "Không có tài khoản $GIT_USER. Đặt GITLAB_GIT_USER."; exit 2; }
+
+rm -rf "$DEST"; mkdir -p "$DEST"
+cp -r "$SRC"/. "$DEST"/; rm -rf "$DEST/.git"
+sed -i "s/^MODE=.*/MODE=$MODE/" "$DEST/gate.conf"
+chown -R root:root "$DEST"; chmod -R a+rX "$DEST"; chmod +x "$DEST"/server/pre-receive "$DEST"/engine/*.sh
+
+mkdir -p "$HOOKS_DIR/pre-receive.d"
+ln -sfn "$DEST/server/pre-receive" "$HOOKS_DIR/pre-receive.d/10-vnptnan-gate"
+chown -R "$GIT_USER":"$GIT_USER" "$HOOKS_DIR"
+
+mkdir -p /var/log/vnptnan-gate; chown "$GIT_USER":"$GIT_USER" /var/log/vnptnan-gate; chmod 750 /var/log/vnptnan-gate
+
+echo "Đã cài VNPTNAN_GATE $(cat "$DEST/VERSION") làm server hook toàn cục (MODE=$MODE)."
+echo "Kiểm tra: đẩy một commit chứa 'AKIAIOSFODNN7EXAMPLE' lên nhánh thử; GitLab phải từ chối với dòng GL-HOOK-ERR."
+echo "Log: /var/log/vnptnan-gate/gate.log. Để quét định kỳ: xem ci/.gitlab-ci.yml khi bật CI."