feat(护栏): 鉴权覆盖审计从"只 WARN"升级为增量即拒绝启动

SecurityConfig 是 anyRequest().permitAll(),方法级 require* 只有 82 处对 401 个 handler,
所以"某个端点没被任何守卫前缀覆盖"这件事只能靠启动自检发现。审计器原先对 uncovered 只打一行
WARN,等于谁忘了登记也不会有人被打断。

改成:存量 uncovered 落 29 条快照进版本控制,profile=server 下**增量**非空即 IllegalStateException
(锚点 [api-guard-coverage-breach])。只拦增量、不拦存量,是为了不重演 10-07 那种"两台起不来"的
41 分钟宕机;判 server profile 复用 JwtService 的同一口径,不另立一套。
This commit is contained in:
2026-10-08 17:36:10 +08:00
parent 419ab3be64
commit f325f88bc3
4 changed files with 552 additions and 2 deletions
@@ -1,13 +1,21 @@
package com.nanri.aiimage.config;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.SmartInitializingSingleton;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.event.EventListener;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.mvc.method.RequestMappingInfo;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashSet;
@@ -33,15 +41,35 @@ import java.util.Set;
* 主机A/B 的巡检(scripts/_prod_watch.py 的 SIGNATURES)把它计入告警。</li>
* </ul>
*
* <p>自检只读不拦:不参与任何请求的放行判定,所以开它没有可用性风险。
* <p>自检只读不拦:不参与任何请求的放行判定,所以开它没有可用性风险。**但 profile=server 时它会拦启动**——
* 见 {@link #afterSingletonsInstantiated()}:快照里不存在的新 uncovered 端点直接拒绝启动,
* 判据形状照 {@code JwtService#requireSecretInServerProfile()}(全树唯一一处"不安全即拒绝启动"的先例)。
*/
@Slf4j
@Component
public class ApiGuardCoverageAuditor {
public class ApiGuardCoverageAuditor implements SmartInitializingSingleton {
/** 巡检锚点:_prod_watch.py 按这个字面量 grep,改名要同时改那条签名。 */
public static final String ALERT_ANCHOR = "API_GUARD_UNCOVERED";
/**
* 增量未设防端点的拒起锚点。异常消息与拒起前的 WARN 都带这一串(含方括号,逐字)。
*
* <p>和 {@link #ALERT_ANCHOR} 分开是有意的:后者是"现网有匿名可达端点"的长期告警,
* 前者是"这一版比上一版多了一个"的发布闸门。两个混用会让人分不清是欠账还是新增。
*/
public static final String BREACH_ANCHOR = "[api-guard-coverage-breach]";
/**
* 存量 uncovered 快照(进版本控制的基线文件,classpath 资源)。
*
* <p>为什么放 {@code src/main/resources/inspection/} 而不是 {@code src/test/resources/}:
* 判增量的是**启动时的审计器**,它跑在生产 jar 里,读不到测试类路径;
* 放 test/resources 等于把基线留在开发机上,现网拿到空基线就会把全部存量报成新增=两台同时起不来。
* {@code inspection/} 已是本模块"可巡检产物"的落位(01–06 号只读报表 SQL 在同目录)。
*/
public static final String BASELINE_RESOURCE = "inspection/api-guard-uncovered-baseline.txt";
/** 设计上匿名可达的基路径。 */
static final Set<String> PUBLIC_BY_DESIGN = Set.of(
"/login", // 登录本身就是发凭据的入口
@@ -109,6 +137,123 @@ public class ApiGuardCoverageAuditor {
this.handlerMapping = handlerMapping;
}
/**
* profile 判定与 {@code JwtService#requireSecretInServerProfile()} 同一口径:
* 读 {@code spring.profiles.active} 这一个 key、用 {@code contains("server")},不另发明一套。
* 两处口径若漂移,就会出现"密钥闸门认为自己是生产、覆盖闸门认为不是"的半拦半放。
* 漂移由 {@code ApiGuardCoverageBreachTest#serverProfilePredicateAgreesWithJwtService} 钉住。
*/
@Value("${spring.profiles.active:}")
private String activeProfiles;
/**
* 增量未设防端点 ⇒ 拒绝启动(仅 profile=server)。
*
* <p>为什么用 {@link SmartInitializingSingleton} 而不是沿用下面那个 {@code ApplicationReadyEvent}:
* {@code afterSingletonsInstantiated()} 在 {@code preInstantiateSingletons()} 收尾时触发,
* 早于 {@code finishRefresh()} 里 Web 服务器绑定端口——抛出去就等价于 {@code JwtService} 的
* {@code @PostConstruct}:容器 refresh 失败、进程非零退出,端口一次都没开。
* 放在 ApplicationReadyEvent 上则要先.listen 再 close,两台同时滚动时等于开了一个匿名可达的窗口。
* 此刻所有单例已创建完,{@code RequestMappingHandlerMapping#afterPropertiesSet} 也已扫完映射,
* 所以 {@link #mappedPaths()} 拿到的是终态集合。
*/
@Override
public void afterSingletonsInstantiated() {
enforceIncrementalCoverage(audit(mappedPaths()).uncovered(),
readBaselineSnapshot(),
isServerProfile(activeProfiles));
}
/**
* 判增量:存量(快照里已登记的)不报错,快照里没有的才拒起。
*
* <p>拆成静态纯方法是为了能被单测直接喂集合——否则"拒起"这条只能靠起真容器验,
* 而那正是本仓库 4035 例全绿却把起不来的 jar 推上线的缺口。
*
* @param uncovered 本轮审计出的未设防端点(已按路径模式去重)
* @param baseline 存量快照里的端点集合
* @param serverProfile 是否按生产口径硬拦
* @throws IllegalStateException 增量非空且 serverProfile ⇒ 消息含 {@link #BREACH_ANCHOR} 与增量清单
*/
static void enforceIncrementalCoverage(Collection<String> uncovered, Set<String> baseline, boolean serverProfile) {
List<String> incremental = incrementalUncovered(uncovered, baseline);
if (incremental.isEmpty()) {
return; // 全存量:由 auditOnBoot 打既有那条 WARN,不拦启动
}
if (!serverProfile) {
log.warn("{} 新增未设防端点 {} 条(profile 非 server,暂不拒起):{} —— 进 AdminApiGuardFilter 名单,"
+ "或确认公开后登记进 PUBLIC_BY_DESIGN 并重生成基线快照",
BREACH_ANCHOR, incremental.size(), incremental);
return;
}
throw new IllegalStateException(BREACH_ANCHOR + " profile=server 下新增 " + incremental.size()
+ " 个未设防端点(不在守卫前缀名单、也不在公开/方法级已设防/待收清单,且不在存量快照 "
+ BASELINE_RESOURCE + " 里)⇒ 拒绝启动,避免它们匿名可达。增量清单=" + incremental
+ ";处置:加进 AdminApiGuardFilter 的名单,或确认公开并登记进 PUBLIC_BY_DESIGN"
+ "(登记同时要更新基线快照,否则下次重启还会拒起)");
}
/**
* 增量 = uncovered 里**逐字不在快照中**的那些。
*
* <p>这里刻意不做前缀匹配:快照记的是端点(路径模式)而不是前缀。
* 若按前缀豁免,登记一条 {@code /api/yolo/list} 就会连带掩护同前缀后来挂上的任何新处理器,
* 而"往没人看守的前缀下再挂一个方法"恰恰是这条护栏唯一要拦的动作。
*/
static List<String> incrementalUncovered(Collection<String> uncovered, Set<String> baseline) {
List<String> out = new ArrayList<>();
for (String path : uncovered) {
if (!baseline.contains(path)) {
out.add(path);
}
}
return out;
}
/** server profile 判据,与 {@code JwtService} 同一句 {@code contains("server")}(含 null 兜底)。 */
static boolean isServerProfile(String activeProfiles) {
return activeProfiles != null && activeProfiles.contains("server");
}
/** 读 {@link #BASELINE_RESOURCE}。缺失或读不动 ⇒ 抛(见方法内注释:不做 fail-open)。 */
static Set<String> readBaselineSnapshot() {
return readBaselineSnapshot(BASELINE_RESOURCE);
}
/**
* 读存量快照:{@code #} 开头与空行忽略,其余 trim 后作为端点路径模式;判据是集合成员关系,顺序无关。
*
* <p><b>刻意 fail-closed</b>:基线不在 classpath 上就抛、拒绝启动,而不是"读不到就跳过增量判定"。
* 后者等于把闸门的开关做成一个可删除的文件——{@code git rm} 掉基线就能让新端点匿名可达,
* 那是"声称保护但其实不保护"的第九种形状。今天现网 uncovered=0,
* 所以这条抛法不会误伤两台(文件随 jar 打包,{@code baselineSnapshotShipsOnTheMainClasspath} 钉着)。
*
* <p>读出来却解析不了同样抛:IOException 走重抛,不静默当成空快照。
*/
static Set<String> readBaselineSnapshot(String resourcePath) {
ClassPathResource resource = new ClassPathResource(resourcePath);
if (!resource.exists()) {
throw new IllegalStateException(BREACH_ANCHOR + " 存量快照 " + resourcePath
+ " 不在 classpath 上 —— 删基线文件不等于收口了欠账,那是把这条闸门关掉;"
+ "要么把文件补回来,要么按 printBaselineSnapshot 重新生成");
}
Set<String> out = new LinkedHashSet<>();
try (InputStream in = resource.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8))) {
String line;
while ((line = reader.readLine()) != null) {
String trimmed = line.trim();
if (!trimmed.isEmpty() && !trimmed.startsWith("#")) {
out.add(trimmed);
}
}
} catch (IOException e) {
throw new IllegalStateException(BREACH_ANCHOR + " 存量快照 " + resourcePath
+ " 读不出来:" + e.getMessage(), e);
}
return out;
}
@EventListener(ApplicationReadyEvent.class)
public void auditOnBoot() {
Report report = audit(mappedPaths());