mcp-baf-audit
Єдиний JSONL-журнал аудиту для сервісів BAF. Формат запису — спільний контракт, щоб логи не розходилися між сервісами.
Пакет повністю незалежний: без рантайм-залежностей, тільки стандартна бібліотека Python (≥3.11). Він нічого не імпортує зі споживачів — навпаки, споживачі залежать від нього.
Споживачі
- mcp-baf — MCP-сервер читання 1С (інтеграція запланована окремим PR).
- baf-write-mcp — MCP-сервер контрольованого створення номенклатури в 1С (вже переведений на цей пакет).
- hermes — інтеграція запланована.
Схема запису (v2)
Кожен рядок журналу — один JSON-об'єкт зі спільним конвертом:
{
"schema_version": "2",
"ts": "2026-06-14T10:51:23.354+00:00",
"service": "baf-write-mcp",
"session": "d6dfd09f2d7d",
"seq": 1043,
"trace_id": "abc123…",
"event": "product.create",
"level": "info",
"tool": "create_product_catalog_item",
"request_id": "req-7",
"object": { "type": "product", "ref": "uuid…", "code": "000001", "name": "Болт" },
"actor": "write-svc",
"source_channel": "mcp",
"ok": true,
"duration_ms": 87,
"status": 200,
"payload": { },
"error": null
}
service — ім'я сервіса (mcp-baf | baf-write-mcp | hermes);
session — hex12, один на процес; seq — монотонний лічильник у сеансі;
trace_id — наскрізний ідентифікатор операції між сервісами, ніколи не
null у нових записах (вкладені події успадковують його через contextvar).
Optional-поля конверта v2 (request_id, object, actor, source_channel,
ok, duration_ms, status) nullable: їхня відсутність у рядку (зокрема в
логах v1) не ламає читання. Редакція секретів застосовується і до payload,
і до object.
Будь-яка зміна формату рядка → bump
SCHEMA_VERSIONуwriter.pyі minor/major тега пакета. v2 додав optional-поля конверта; читач розуміє і v1, і v2.
Канонічні імена подій
events.py фіксує namespaced-таксономію (tool.call, product.create,
counterparty.propose, one_c.http, index.search, …). Writer нормалізує
ім'я кожного запису через canonical(), тож нові логи завжди канонічні —
навіть якщо доменний код передає звичне плоске ім'я. Старі логи лишаються
читабельними: той самий canonical() мапить плоскі імена v1 у канонічні.
from mcp_baf_audit import canonical, events
canonical("create") # -> "product.create"
canonical("tool_call") # -> "tool.call"
canonical("product.create") # -> "product.create" (ідемпотентно)
events.PRODUCT_CREATE # "product.create"
Використання
from mcp_baf_audit import AuditWriter, traced, iter_events
audit = AuditWriter(service="mcp-baf", path="/path/to/audit.log")
audit.server_start(version="1.2.3")
# Канонічний метод v2 (payload і object редагуються від секретів):
audit.event("product.create", tool="create_product_catalog_item",
request_id="req-7", status=200, duration_ms=12, ok=True,
obj={"type": "product", "ref": "uuid…", "name": "Болт"},
payload={"name": "Болт"})
# Обгортка інструмента: пише tool.call/tool.error, міряє duration,
# гарантує не-null trace_id (явний -> contextvar -> новий) і фіксує його
# в contextvar, щоб вкладені події успадкували.
result_json = await traced(audit, "query", call, args={"limit": 10})
Читання журналу
iter_events() — єдина читацька функція. Вона обходить ротовані архіви в
хронологічному порядку, мовчки пропускає биті рядки (повідомляє про кожен
через on_bad_line) і нормалізує event через canonical(). На ній
будуються зовнішні проєкція/дашборд — сама бібліотека ні БД, ні форматів
представлення не знає.
from mcp_baf_audit import iter_events
bad: list[str] = []
for ev in iter_events("/path/to/audit.log", on_bad_line=bad.append):
print(ev["seq"], ev["event"], ev.get("trace_id"))
print("пропущено битих рядків:", len(bad))
HTTP-події one_c.http
baf-write-mcp передає аудит у HTTP-клієнт (OneCClient(config, audit=audit)),
і кожен виклик 1С лишає рівно одну подію one_c.http (метод, ендпоінт,
статус, duration_ms, response_bytes, request_id, trace_id). Тіло
запиту/відповіді не логується; помилки пишуться з level:"error", ok:false.
Секрети
Редакція централізована у writer'і: ключі password|token|authorization|secret
(регістронезалежно, рекурсивно) замінюються на *** у кожному записі.
Передавати «сирий» payload безпечно — секрети у лог не потрапляють.
Постачання / версіонування
Тег v0.2.0 (minor-bump: формат запису перейшов на schema v2). Споживачі
пінять версію:
pip install "git+https://github.com/andriy4k07/mcp-baf-audit.git@v0.2.0"
У монорепо — path-залежність від сусіднього каталогу:
pip install -e ../mcp-baf-audit
Metadata
Release files for mcp-baf-audit 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_baf_audit-0.2.1.tar.gz | 21.2 kB | Without provenance | Details for mcp_baf_audit-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_baf_audit-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for mcp_baf_audit-0.2.1-py3-none-any.whl |
Total release size: 38.1 kB
Release files / mcp_baf_audit-0.2.1.tar.gz
| Download URL | mcp_baf_audit-0.2.1.tar.gz |
|---|---|
| Size | 21.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
597702230fa3ac037ec79f2ce22a9b85ed3c1b2d51118c3e39c0032565b96d66
|
|
BLAKE2b-256 checksum How to use checksums |
0dc884a24cd55d4ed909d4e525362e813f6136333dc9e12c4fa7eb59a1cf24da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mcp_baf_audit-0.2.1-py3-none-any.whl
| Download URL | mcp_baf_audit-0.2.1-py3-none-any.whl |
|---|---|
| Size | 16.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2caefb8a5a9aad39106009c45e37eae995ae5f5e45df05b6458bc63c7578ab38
|
|
BLAKE2b-256 checksum How to use checksums |
31cd8b05ca69d6edcb0a78a3d0fa7239fb31dcc66859acf87717facb9103dce8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mcp-baf-audit 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.