bashguard

type Decision struct {
	// ReadOnly 命令可判只读（不执行任何写路径）。
	ReadOnly bool
	// Reason 非只读原因（人可读，审计用）。
	Reason string
	// Destructive 该调用含不可逆动作（删数据 / 写设备 / 关机 / 递归改权限 …）。
	//
	// 与 ReadOnly **正交**：只读与否是另一档。一个命令可以「不是只读、但可逆」
	//（rm file），也可以「不是只读、且不可逆」（rm -rf /）。
	//
	// 语义边界：false 只意味着「没命中已知规则」，**不意味着安全**——
	// 是否要二次确认是调用方的策略决定，本包只给「这条命令不可逆」这个事实。
	Destructive bool
	// DestructiveReason 不可逆依据（人可读，审计用）；未命中时为空。
	DestructiveReason string
	// Unevaluated 命令未进 AST 判定（超长未进解析器 / 解析失败，tools#45）。
	//
	// 此时 ReadOnly=false 只是保守拒，**Destructive=false 不再意味着「判了
	// 不不可逆」**——未评估就是不可判：「判据不可判」与「判了不不可逆」不得
	// 压成同一个信号。调用方对未评估输入须按保守侧处理（如照常要二次确认），
	// 不得当「已判安全」。超长路径另有头/尾窗 best-effort 扫描兜底（见
	// overlongDecision）：窗口内命中的不可逆动作照常置 Destructive。
	//
	// 细分归因见 OverLength / Unparsed（tools#80）：未评估的伞标记在此，
	// 两细分只回答「为什么没判」，两者置位时本标记必置位。
	Unevaluated bool
	// OverLength 命令超过 MaxCommandLen 未进解析器（tools#80）：Unevaluated
	// 的细分归因之一。集成方据此区分「超长拒绝判定」与「解析失败拒绝判定」，
	// 并与「判定完成没发现风险」（Unevaluated/OverLength/Unparsed 全 false）
	// 相区分——拒绝判定（任一标记置位）时 ReadOnly=false 只是保守拒，命令
	// 文本里的实际风险（如 10KB 注释填充后尾随的 rm -rf …）未被评估，调用方
	// 须自行升级处置（如照常要确认）。
	OverLength bool
	// Unparsed 解析失败未进 AST 判定（tools#80）：Unevaluated 的细分归因之一，
	// 语义同 OverLength（拒绝判定，须按保守侧处理）。
	Unparsed bool
	// Invocations 提取的调用序列（观测/风险面）。
	//
	// ⚠️ 这是**判定路径**的消费序列，不是全量事实：判定在首个非只读调用上
	// 提前返回（Analyze 的 break），其后的调用不再评估；包装剥壳后判定的是
	// 内核，调用面记录的是包装（sudo -n rm 只见 sudo）。做确认门禁/风险审计
	// 请用 AllCalls（见其注释）。
	Invocations []Invocation
	// AllCalls 全 AST 的 simple command 集合（syntax.Walk，oagentkit/tools#35）：
	// 管道后半、命令替换 $(…)、子 shell (…)、{ …; } 里的调用**全部可见**，
	// 与判定路径是否提前返回无关。
	//
	// 与 Invocations 的分工：Invocations 服务 ReadOnly/Destructive 判定的
	// 归因（为何判非只读）；AllCalls 服务「这条命令文本里**出现了什么**」的
	// 风险面事实——jumpserver-kit 此前为补这个集合在守卫层自接了一份
	// syntax.Walk（判定门禁的绕过全堵上依赖它），重复实现会漂、漂的那份
	// 决定门禁拦什么，故上游收编。
	//
	// 语义边界（调用方须知）：
	//   - 包装不剥壳：sudo -n rm -rf /x 是一条调用（sudo，args 含 rm…）——
	//     sudo/xargs/env 的内核是**参数**不是语法调用，消费方按需自剥
	//     （本包自身的不可逆扫描已对未注册调度器做内核兜底，见
	//     destructive.go 的 destructiveKernel）；
	//   - eval "rm -rf /x" 的 rm 是字符串数据不是语法调用，只见 eval；
	//   - Dynamic=true 的调用（参数含 $()/反引号/$VAR）同样入列——动态参数
	//     本身就是风险信号。
	AllCalls []Invocation
	// Redirs 全 AST 的重定向事实集（syntax.Walk，tools#79）：语句级、子 shell
	// (…)、{ …; }、命令替换 $(…) 里的重定向全部可见，与判定路径是否提前返回
	// 无关。服务集成方的重定向目标判定（写块设备等走 Redirs 不走调用面），
	// 免集成方为拿重定向再 parse 一遍同一命令（与 AllCalls 的收编动机同型）。
	//
	// 语义边界见 RedirInfo：heredoc 体不在此结构；写重定向（Read=false）本身
	// 已使命令非只读，本事实面供非只读之后的目标细分。超长路径为头/尾窗
	// best-effort 收集（重叠区去重，与 AllCalls 同法）；解析失败为空。
	Redirs []RedirInfo
}

type FlagKind string

type Invocation struct {
	Name    string
	Args    []string
	Dynamic bool // 含动态词（argv 非字面）
}

type Policy struct {
	// ReadOnly 命令本体是否只读。
	ReadOnly bool
	// SafeFlags 已知安全 flag（含 - 前缀，如 "-n"）。长 flag 单写。
	SafeFlags map[string]FlagKind
	// UnsafeFlags 命中即非只读（显式优先于 SafeFlags）。
	UnsafeFlags []string
	// Subcommands 子命令策略表（git 形态，可嵌套）：子命令不在表=非只读。
	Subcommands map[string]Policy
	// Wrapper 安全包装（env/timeout 形态）：剥壳后按剩余首参判定。
	Wrapper bool
	// ConsumeBare Wrapper 剥 flag 后先吃掉的前置裸操作数个数（timeout 的时长）。
	ConsumeBare int
	// NoBareOperands 裸操作数即写形态（git branch <名> 创建 / git stash 裸 push /
	// git tag <名> 打标）：出现任何 flag 之外的裸操作数 → 非只读。
	NoBareOperands bool
	// AllowBareOperandsPrefix NoBareOperands 的豁免前缀（date 的 +FORMAT 形态：
	// 裸操作数以 "+" 开头是格式串不是写目标）。前缀空串不放行任何操作数。
	AllowBareOperandsPrefix []string
	// CheckArgs 参数深度校验钩子（tools#81）：flag 表表达不了的 mini-language
	// 参数面（sed 脚本：w/W 写文件、e/s///e 执行命令可藏于裸操作数与 -e/
	// --expression 的**值**里，flag 白名单与 NoBareOperands 都看不到内容）。
	// 收到完整 argv（含 flag 及其值），返回非空串=非只读原因。
	//
	// 调用时机：叶子路径（evalLeafPolicy）在白名单 flag 消费**之后**——未知
	// flag 先被表拒，钩子只处理表放过来的形态；子命令/包装路径不调用。实现
	// 必须自带 fail-closed 纪律（看不懂的一律拒），钩子内不执行任何命令。
	CheckArgs func(name string, argv []string) string
	// Destructive 该命令恒不可逆（删数据 / 写设备 / 关机 …）。
	//
	// 只在**不可逆规则表**（Table.Destructive）里有意义——只读表是只读表，
	// 不可逆判据单列一张（见 destructive.go 的说明）。
	Destructive bool
	// DestructiveFlags 命中即不可逆的 flag（"-r" / "--recursive"）。
	// 短 flag 支持联合形态（-rf 里的 r）。
	DestructiveFlags []string
	// DestructiveArgs 命中即不可逆的参数（**前缀**匹配："of=" 命中 "of=/dev/sda"）。
	DestructiveArgs []string
}

type RedirInfo struct {
	Op      string // 操作符字面（">" / ">>" / "&>" / "<" / "<<" / "<<<" …）
	FD      int    // 作用的目标 fd：">" 默认 1、"2>" 为 2；{varname}> 形态为 -1（fd 由运行时变量决定）
	Target  string // 目标词字面化文本（heredoc 为定界符；含展开时为拼接的部分文本，Dynamic=true）
	Dynamic bool   // 目标词含动态展开（$()/反引号/$VAR）
	Read    bool   // 读侧重定向（<、<<、<<-、<<<）：目标是被读的源，不产生写
}

type RiskTier string

type Table struct {
	Commands map[string]Policy
	// Destructive 不可逆规则表：命令名 → 判据（只用 Policy 的三个 Destructive* 字段）。
	//
	// 与只读表**分开**：只读表只放只读命令（"不在只读策略表" 是既有语义），
	// 而不可逆判据要覆盖 rm / mkfs / dd 这类写命令。键尾的 "*" 表示前缀族
	//（"mkfs*" 覆盖 mkfs.ext4 等）。
	Destructive map[string]Policy
}