audit¶
按路由区分的工具调用所使用的 append-only JSONL 审计轨迹:build_record、
append_record、artifact_paths 与 resolve_audit_path,以及让 prompt、图像载荷与凭据
不进入轨迹的脱敏辅助函数。
参见
Insiders 头、分路与审计
了解记录在何时写入,以及
配置 中的 MCP_AUDIT_LOG_PATH。
Append-only JSONL audit trail for routed tool calls.
One record per line, one os.write per record. The file is opened with
O_APPEND so concurrent writers append whole lines rather than overwrite one
another: a crash mid-write can lose a line but never corrupt a line already
written.
Nothing here may break a tool call. Every I/O or serialisation failure is logged and swallowed, because observability must never become a dependency of the business path.
Credentials and image payloads are never recorded. Prompts are reduced to their length plus a truncated SHA-256, image arguments are replaced by a marker, and any over-long string is digested instead of written verbatim, so a base64 blob cannot reach the trail even under an unexpected argument name.
- novelai_image_mcp.audit.AUDIT_FILENAME = 'audit.jsonl'¶
File name used when no explicit audit path is configured.
- novelai_image_mcp.audit.DIGEST_LENGTH = 16¶
Number of hex characters kept from a digest.
- novelai_image_mcp.audit.MAX_ARGUMENT_LENGTH = 256¶
Longest argument string recorded verbatim; longer values are digested.
- novelai_image_mcp.audit.MAX_RECORDED_HEADERS = 32¶
Largest number of headers kept in an audit record. The routing layer already caps its snapshot at 64; this is a second, tighter bound so a hostile client cannot grow an audit line without limit.
- novelai_image_mcp.audit.MAX_RECORDED_HEADER_LENGTH = 256¶
Longest header value kept in an audit record.
- novelai_image_mcp.audit.append_record(record, *, path)[源代码]¶
Append
recordas a single JSON line; return whether it was written.The record is serialised first and then handed to exactly one
os.writeon a descriptor openedO_APPEND, so concurrent writers cannot interleave halves of a line. Failures are logged and reported asFalse-- this function never raises, because a tool call must not fail on account of the audit trail.
- novelai_image_mcp.audit.artifact_paths(result)[源代码]¶
Return the sorted
*.pngpaths a tool result mentions.Image tools report what they wrote as text (
Saved 1 image(s): [...]); this reads those paths back for the audit record. The result is only observed, never rewritten, and a result without text blocks yields[].
- novelai_image_mcp.audit.build_record(*, routing, tool, duration_ms, outcome, features=(), artifacts=(), arguments=None, unknown_keys=(), malformed=())[源代码]¶
Build one JSON-serialisable audit record.
features,artifacts,unknown_keysandmalformedare sorted so two records describing the same state are byte-identical.
- novelai_image_mcp.audit.cap_headers(headers)[源代码]¶
Apply the audit-side cap to an already-sanitised header snapshot.
The input is expected to be
RoutingContext.recorded_headers, which the routing layer has already stripped of every credential-bearing name. This only bounds the size: at most :data:MAX_RECORDED_HEADERSentries, each value at most :data:MAX_RECORDED_HEADER_LENGTHcharacters, kept in lexicographic order of the (lower-cased) name.
- novelai_image_mcp.audit.digest_text(value)[源代码]¶
Return the length and truncated SHA-256 of
value, never the text.
- novelai_image_mcp.audit.resolve_audit_path(*, audit_log_path, output_dir=None)[源代码]¶
Resolve the audit destination.
An explicit
audit_log_pathwins; otherwise the trail lives beside the generated images at<output_dir>/audit.jsonl.
- novelai_image_mcp.audit.summarise_arguments(arguments)[源代码]¶
Summarise tool arguments so the record can never leak a payload.
Prompts become a length plus a truncated SHA-256, image arguments become a marker, and every other value is reduced to something small and JSON-serialisable.
记录何时写入¶
审计轨迹是 insiders 接口面的一部分:ToolCallLoggingMiddleware
每次工具调用追加一条记录,且仅在 model-routing 生效期间。不发送 opt-in 头的
请求不会写入任何内容。
resolve_audit_path 选择目标位置 —— 显式的
MCP_AUDIT_LOG_PATH 优先,否则取
NOVELAI_OUTPUT_DIR 下的 audit.jsonl。
记录字段¶
build_record 每次调用产出一个扁平的、可 JSON 序列化的对象:
字段 |
内容 |
|---|---|
|
UTC 时间戳,ISO-8601。 |
|
净化后的 route。 |
|
提取出的路由值,或 |
|
工具名。 |
|
墙上时钟耗时,四舍五入到三位小数。 |
|
|
|
当前生效的 insiders 特性的排序后名字。 |
|
结果中提到的 |
|
insiders 头中无法识别的键,已排序。 |
|
insiders 头中不可用的条目,已排序。 |
|
净化后的路由头快照,上限为 |
|
摘要化后的调用参数 —— 见下文。 |
features、artifacts、unknown_keys 与 malformed 会被排序,因此描述同一状态的
两条记录逐字节相同。
脱敏¶
summarise_arguments 会在任何参数进入文件之前先将其缩减:
形如 prompt 的参数(
prompt、prompts、negative_prompt、negativeprompt)经digest_text变为{"length": n, "sha256": "<first 16 hex characters>"}。prompt 文本永远不会被写入。形如图像的参数(
image、images、init_image、mask、reference、references、base64)变为字面量[redacted image]。任何长度超过
MAX_ARGUMENT_LENGTH(256)的字符串都会被 摘要化而不是直接写入,因此一个 base64 blob 无法借某个 意料之外的参数名溜过去。映射被缩减为
{"keys": n};列表、元组与集合被缩减为{"items": n};任何其他对象缩减为其类型名。None、布尔值、整数 与浮点数按原样记录。
携带凭据的头会由
routing._recorded 在上游移除,因此本模块所限制的快照从一开始就不含
authorization、cookie、set-cookie、proxy-authorization 或任何
*-token / *-secret / *-password / *-key / *-credential
头。
并发与持久性¶
append_record 先序列化记录,然后用恰好一次 os.write 写入到
以 O_APPEND 打开的描述符(模式 0o600,
必要时创建父目录)。因此并发写入者追加的是
完整行,而不会把同一行从中间交错:写入中途崩溃可能丢掉一行,
但不会破坏已经写好的行。
失败行为¶
可观测性永远不会成为业务路径的依赖。
append_record 捕获自身的 OSError / TypeError / ValueError,
用 logger.error 记录该失败,并返回 False —— 它从不抛出,因此
不存在任何一条代码路径会让不可写的审计文件变成
工具调用失败。
参见¶
Insiders 头、分路与审计 —— 头语法与 route 解析
middleware—— 追加这些记录的调用方routing—— 本模块所限制的头快照