aiauditlog 0.1.0a3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aiauditlog-0.1.0a3/.gitignore +17 -0
- aiauditlog-0.1.0a3/CHANGELOG.md +21 -0
- aiauditlog-0.1.0a3/LICENSE +21 -0
- aiauditlog-0.1.0a3/PKG-INFO +299 -0
- aiauditlog-0.1.0a3/README.md +259 -0
- aiauditlog-0.1.0a3/docs/api.md +22 -0
- aiauditlog-0.1.0a3/docs/cli.md +26 -0
- aiauditlog-0.1.0a3/docs/event-envelope.md +17 -0
- aiauditlog-0.1.0a3/docs/getting-started.md +40 -0
- aiauditlog-0.1.0a3/docs/interoperability.md +24 -0
- aiauditlog-0.1.0a3/docs/roadmap.md +43 -0
- aiauditlog-0.1.0a3/docs/security.md +33 -0
- aiauditlog-0.1.0a3/examples/basic/event.json +57 -0
- aiauditlog-0.1.0a3/examples/basic/legacy-event.json +19 -0
- aiauditlog-0.1.0a3/examples/privacy/minimal.yaml +18 -0
- aiauditlog-0.1.0a3/examples/tampered/README.md +5 -0
- aiauditlog-0.1.0a3/pyproject.toml +105 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/__init__.py +45 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/adapters.py +35 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/builder.py +48 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/canonical.py +60 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/chain.py +99 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/checkpoint.py +80 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/checkpoint_policy.py +78 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/cli.py +337 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/compression.py +29 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/constants.py +127 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/digest.py +36 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/ecosystem.py +111 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/exceptions.py +25 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/exports.py +75 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/ids.py +22 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/migration.py +47 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/models.py +330 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/otel.py +29 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/privacy.py +162 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/py.typed +1 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/query.py +33 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/recorder.py +53 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/reports.py +70 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/rotation.py +70 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/schema.py +31 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/schemas/audit-event-v1.schema.json +804 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/signatures.py +133 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/storage.py +237 -0
- aiauditlog-0.1.0a3/src/ai_audit_log/time.py +38 -0
- aiauditlog-0.1.0a3/tests/test_core.py +202 -0
- aiauditlog-0.1.0a3/tests/test_roadmap_a2_a3.py +187 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to AIAuditLog are documented here.
|
|
4
|
+
|
|
5
|
+
## 0.1.0a3 - Unreleased
|
|
6
|
+
|
|
7
|
+
- Add a versioned, typed audit-event envelope and packaged JSON Schema.
|
|
8
|
+
- Add RFC 8785-backed serialization after AIAuditLog-specific value normalization.
|
|
9
|
+
- Add SHA-256 event digests, optional hash chains, stream verification, and checkpoints.
|
|
10
|
+
- Add optional Ed25519 checkpoint signatures and signature policies.
|
|
11
|
+
- Add JSONL storage, optional SQLite indexing, querying, summaries, rotation, and migration helpers.
|
|
12
|
+
- Add privacy profiles, heuristic secret filtering and classification redaction.
|
|
13
|
+
- Add JSON, JSONL, CSV-safe, Markdown, redacted, and deterministic gzip exports.
|
|
14
|
+
- Add W3C Trace Context helpers and neutral dictionary-based ecosystem adapters.
|
|
15
|
+
- Add the `aiaudit` CLI and typed Python API.
|
|
16
|
+
|
|
17
|
+
This is alpha software. Hash chaining is tamper-evident, not immutable. Signatures
|
|
18
|
+
authenticate bytes to a key but do not prove real-world identity or legal
|
|
19
|
+
non-repudiation. Privacy filtering is heuristic. This release does not provide
|
|
20
|
+
automatic compliance, immutable storage, trusted timestamping, or external
|
|
21
|
+
anchoring. Neutral adapters have not been tested against sibling packages.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 sekacorn
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: aiauditlog
|
|
3
|
+
Version: 0.1.0a3
|
|
4
|
+
Summary: A vendor-neutral, tamper-evident audit-event format and local toolkit for AI systems and agents.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sekacorn/AIAuditLog
|
|
6
|
+
Project-URL: Repository, https://github.com/sekacorn/AIAuditLog
|
|
7
|
+
Project-URL: Issues, https://github.com/sekacorn/AIAuditLog/issues
|
|
8
|
+
Project-URL: Documentation, https://github.com/sekacorn/AIAuditLog/tree/main/docs
|
|
9
|
+
Author: sekacorn
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Security
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
21
|
+
Classifier: Topic :: System :: Logging
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: <3.14,>=3.11
|
|
24
|
+
Requires-Dist: cryptography>=48.0.1
|
|
25
|
+
Requires-Dist: pydantic>=2.7
|
|
26
|
+
Requires-Dist: pyyaml>=6
|
|
27
|
+
Requires-Dist: rfc8785>=0.1.4
|
|
28
|
+
Requires-Dist: typer>=0.12
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
|
|
31
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
32
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
33
|
+
Requires-Dist: pip-audit>=2.7; extra == 'dev'
|
|
34
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
35
|
+
Requires-Dist: pytest>=9.0.3; extra == 'dev'
|
|
36
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
37
|
+
Requires-Dist: twine>=5; extra == 'dev'
|
|
38
|
+
Requires-Dist: types-pyyaml>=6; extra == 'dev'
|
|
39
|
+
Description-Content-Type: text/markdown
|
|
40
|
+
|
|
41
|
+
# AIAuditLog
|
|
42
|
+
|
|
43
|
+
AIAuditLog provides portable, privacy-aware, tamper-evident evidence for AI
|
|
44
|
+
models, agents, tools, policies, reviews, and workflow outcomes.
|
|
45
|
+
|
|
46
|
+
This is an alpha release candidate for `0.1.0a3`. It is ready for public alpha
|
|
47
|
+
release with documented limitations, not production certification.
|
|
48
|
+
|
|
49
|
+
## Why AI Audit Logs Are Different
|
|
50
|
+
|
|
51
|
+
Ordinary application logs usually explain what software printed while it ran.
|
|
52
|
+
AI audit evidence must also preserve model choices, tool access, policy
|
|
53
|
+
decisions, human approvals, data references, redaction decisions, and workflow
|
|
54
|
+
outcomes in a vendor-neutral format that survives framework and provider
|
|
55
|
+
changes.
|
|
56
|
+
|
|
57
|
+
## Problem Statement
|
|
58
|
+
|
|
59
|
+
Organizations need inspectable evidence of what an AI system did, why it acted,
|
|
60
|
+
which models and policies were involved, what data and tools were accessed, and
|
|
61
|
+
what outcome occurred. AIAuditLog keeps that evidence local-first, append
|
|
62
|
+
oriented, deterministic, and suitable for CI review.
|
|
63
|
+
|
|
64
|
+
## Ecosystem Position
|
|
65
|
+
|
|
66
|
+
AIAuditLog is project six in the sekacorn AI infrastructure roadmap. It is
|
|
67
|
+
designed for future optional integration with Forge, PrivateAIStack,
|
|
68
|
+
ModelSwapBench, OpenOntologyLite, AgentPolicyPack, and OpenAIMeter. The first
|
|
69
|
+
alpha works independently and offline.
|
|
70
|
+
|
|
71
|
+
## Core Capabilities
|
|
72
|
+
|
|
73
|
+
- Versioned JSON event envelope and JSON Schema export.
|
|
74
|
+
- Typed Python models for AI, agent, tool, policy, ontology, and benchmark context.
|
|
75
|
+
- RFC8785-backed canonical JSON after AIAuditLog value normalization.
|
|
76
|
+
- SHA-256 event digests.
|
|
77
|
+
- Optional hash-chain metadata for tamper evidence.
|
|
78
|
+
- Checkpoints, optional Ed25519 checkpoint signatures, and signature policies.
|
|
79
|
+
- JSONL storage and SQLite indexing.
|
|
80
|
+
- Stream rotation, lock-file guarded appends, compressed exports, and schema migration helpers.
|
|
81
|
+
- Privacy modes, deterministic redaction, secret-key filtering, classification redaction, and CSV-safe export.
|
|
82
|
+
- CLI and Python API.
|
|
83
|
+
- Neutral adapter protocols for future ecosystem packages.
|
|
84
|
+
|
|
85
|
+
## Event Architecture
|
|
86
|
+
|
|
87
|
+
Each event contains `schema_version`, `event_id`, `event_type`, UTC
|
|
88
|
+
`event_time`, UTC `recorded_time`, `source`, `actor`, `outcome`, `data`,
|
|
89
|
+
optional context, and `integrity`. Core event types cover system, agent, model,
|
|
90
|
+
tool, data, retrieval, policy, review, security, evaluation, benchmark, and
|
|
91
|
+
audit-log lifecycle categories. Custom event types must be namespaced and may
|
|
92
|
+
not collide with reserved core namespaces.
|
|
93
|
+
|
|
94
|
+
## Installation
|
|
95
|
+
|
|
96
|
+
```powershell
|
|
97
|
+
python -m pip install aiauditlog
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
For development:
|
|
101
|
+
|
|
102
|
+
```powershell
|
|
103
|
+
python -m pip install -e ".[dev]"
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Quick Start
|
|
107
|
+
|
|
108
|
+
```powershell
|
|
109
|
+
aiaudit validate examples/basic/event.json
|
|
110
|
+
aiaudit append build/audit.jsonl --event examples/basic/event.json
|
|
111
|
+
aiaudit verify build/audit.jsonl
|
|
112
|
+
aiaudit summarize build/audit.jsonl
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## JSON Event Example
|
|
116
|
+
|
|
117
|
+
See `examples/basic/event.json` for a complete model invocation event. Prompts
|
|
118
|
+
and responses are not stored by default; use hashes, references, counts, and
|
|
119
|
+
explicitly configured safe excerpts.
|
|
120
|
+
|
|
121
|
+
## Recorder Example
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
from ai_audit_log import AuditRecorder, EventBuilder, JsonlStore, Outcome, Source
|
|
125
|
+
from ai_audit_log.models import Actor
|
|
126
|
+
|
|
127
|
+
builder = EventBuilder(
|
|
128
|
+
source=Source(service="claims-agent"),
|
|
129
|
+
actor=Actor(actor_id="agent-17", actor_type="ai_agent"),
|
|
130
|
+
)
|
|
131
|
+
recorder = AuditRecorder(builder=builder, store=JsonlStore("build/audit.jsonl"))
|
|
132
|
+
recorder.record(
|
|
133
|
+
event_type="model.invocation.completed",
|
|
134
|
+
outcome=Outcome(status="success", code="COMPLETED"),
|
|
135
|
+
data={"provider": "example", "model_name": "example-model"},
|
|
136
|
+
)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Chain Verification
|
|
140
|
+
|
|
141
|
+
```powershell
|
|
142
|
+
aiaudit verify build/audit.jsonl
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Hash chaining is tamper-evident, not immutable. An attacker who can rewrite an
|
|
146
|
+
entire unsigned log can recompute the chain.
|
|
147
|
+
|
|
148
|
+
## Privacy Modes
|
|
149
|
+
|
|
150
|
+
The default mode is `minimal`: identifiers, metadata, hashes, counts, outcomes,
|
|
151
|
+
and policy evidence are preserved, while prompts, responses, and common secret
|
|
152
|
+
keys are redacted. `balanced` may keep short configured excerpts.
|
|
153
|
+
`full-content` requires explicit opt-in and can expose sensitive data.
|
|
154
|
+
|
|
155
|
+
## Checkpoints And Signatures
|
|
156
|
+
|
|
157
|
+
Checkpoints summarize stream ID, event count, terminal digest, and checkpoint
|
|
158
|
+
digest. Ed25519 signatures authenticate the checkpoint bytes to a public key,
|
|
159
|
+
and checkpoint signature policies can require allowed key IDs, fingerprints, and
|
|
160
|
+
minimum signature counts. Signatures do not prove real-world actor identity,
|
|
161
|
+
legal non-repudiation, or correct key custody.
|
|
162
|
+
|
|
163
|
+
```powershell
|
|
164
|
+
aiaudit checkpoint create build/audit.jsonl --output build/checkpoint.json
|
|
165
|
+
aiaudit key generate --private-key build/development-private.pem --public-key build/development-public.pem
|
|
166
|
+
aiaudit sign build/checkpoint.json --private-key build/development-private.pem --key-id development-key
|
|
167
|
+
aiaudit signature verify build/checkpoint.json --public-key build/development-public.pem
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Never commit generated private keys.
|
|
171
|
+
|
|
172
|
+
## CLI Examples
|
|
173
|
+
|
|
174
|
+
```powershell
|
|
175
|
+
aiaudit inspect examples/basic/event.json
|
|
176
|
+
aiaudit query build/audit.jsonl --event-type model.invocation.completed
|
|
177
|
+
aiaudit export build/audit.jsonl --format markdown --output build/audit-report.md --compress
|
|
178
|
+
aiaudit redact build/audit.jsonl --profile examples/privacy/minimal.yaml --output build/audit-redacted.jsonl
|
|
179
|
+
aiaudit migrate examples/basic/legacy-event.json --output build/migrated-event.json
|
|
180
|
+
aiaudit rotate build/audit.jsonl
|
|
181
|
+
aiaudit schema list
|
|
182
|
+
aiaudit schema export --output build/schemas
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Storage
|
|
186
|
+
|
|
187
|
+
JSONL is the canonical local stream format. SQLite indexing is optional and is
|
|
188
|
+
not tamper-proof; chain verification recalculates event digests from stored
|
|
189
|
+
events.
|
|
190
|
+
|
|
191
|
+
## Adapters
|
|
192
|
+
|
|
193
|
+
The package includes neutral protocols for framework, policy, ontology, and
|
|
194
|
+
benchmark adapters. No external ecosystem package is required in core.
|
|
195
|
+
|
|
196
|
+
## Security Model
|
|
197
|
+
|
|
198
|
+
AIAuditLog distinguishes application logs, telemetry, audit evidence,
|
|
199
|
+
cryptographic integrity, authenticity, non-repudiation, and legal
|
|
200
|
+
admissibility. It provides local tamper evidence and optional checkpoint
|
|
201
|
+
signatures. It does not provide immutable storage, identity proofing, legal
|
|
202
|
+
certification, a SIEM, or policy enforcement.
|
|
203
|
+
|
|
204
|
+
## Threat Model And Limitations
|
|
205
|
+
|
|
206
|
+
- Hash chaining is tamper-evident, not immutable.
|
|
207
|
+
- An attacker who can rewrite the entire log may recompute an unsigned chain.
|
|
208
|
+
- Signatures depend on secure key custody.
|
|
209
|
+
- The package does not establish real-world actor identity.
|
|
210
|
+
- Timestamps depend on system clocks.
|
|
211
|
+
- Local storage can be deleted.
|
|
212
|
+
- SQLite is not tamper-proof.
|
|
213
|
+
- Full-content logging may expose sensitive data.
|
|
214
|
+
- Redaction and secret detection are heuristic and not perfect.
|
|
215
|
+
- Adapters depend on external framework APIs.
|
|
216
|
+
- Event completeness depends on correct instrumentation.
|
|
217
|
+
- Missing events cannot always be distinguished from actions that never occurred.
|
|
218
|
+
- Audit records do not guarantee model correctness.
|
|
219
|
+
- Audit records do not enforce policy.
|
|
220
|
+
- Compliance mappings are informational.
|
|
221
|
+
- This project is not legal advice.
|
|
222
|
+
- The schema may evolve before version 1.0.
|
|
223
|
+
- External anchoring and trusted timestamping are not included in this alpha.
|
|
224
|
+
- Concurrent multi-process writing has documented limitations unless explicitly tested.
|
|
225
|
+
|
|
226
|
+
## Interoperability
|
|
227
|
+
|
|
228
|
+
Canonical JSON serialization uses the maintained `rfc8785` package after
|
|
229
|
+
AIAuditLog normalizes datetimes, Decimals, bytes, and model objects. Timestamps
|
|
230
|
+
are RFC 3339-compatible UTC strings. Trace and span fields can carry W3C Trace
|
|
231
|
+
Context or OpenTelemetry identifiers, and helper functions can parse and emit
|
|
232
|
+
`traceparent` values. CloudEvents concepts influenced envelope naming, but this
|
|
233
|
+
package does not claim CloudEvents compliance.
|
|
234
|
+
|
|
235
|
+
## Roadmap
|
|
236
|
+
|
|
237
|
+
Implemented in 0.1.0a2:
|
|
238
|
+
|
|
239
|
+
- RFC8785-backed canonicalization with an RFC8785 sample vector.
|
|
240
|
+
- Signed checkpoint policies.
|
|
241
|
+
- Stream rotation.
|
|
242
|
+
- Deterministic gzip exports.
|
|
243
|
+
- Richer privacy profiles.
|
|
244
|
+
- Lock-file guarded appends.
|
|
245
|
+
- Conservative schema migration helpers.
|
|
246
|
+
|
|
247
|
+
Implemented in 0.1.0a3:
|
|
248
|
+
|
|
249
|
+
- Neutral Forge-like agent step adapter.
|
|
250
|
+
- Neutral AgentPolicyPack-like policy decision adapter.
|
|
251
|
+
- Neutral ModelSwapBench-like benchmark context adapter.
|
|
252
|
+
- Neutral OpenOntologyLite-like ontology context adapter.
|
|
253
|
+
- Neutral PrivateAIStack metadata adapter.
|
|
254
|
+
- OpenTelemetry/W3C Trace Context helpers.
|
|
255
|
+
|
|
256
|
+
The 0.1.0a3 adapters intentionally use plain dictionaries and are not claimed as
|
|
257
|
+
externally tested against sibling packages.
|
|
258
|
+
|
|
259
|
+
Next candidates for 0.1.0a4:
|
|
260
|
+
|
|
261
|
+
- Broader export test coverage for JSON, JSONL, CSV, Markdown, and compressed outputs.
|
|
262
|
+
- Signed stream manifests.
|
|
263
|
+
- Stronger rotation manifests and rotation verification.
|
|
264
|
+
- More complete schema migration fixtures.
|
|
265
|
+
- Optional dependency-license report generation.
|
|
266
|
+
- Improved concurrent-writer stress tests.
|
|
267
|
+
|
|
268
|
+
0.2 candidates:
|
|
269
|
+
|
|
270
|
+
- External checkpoint anchoring.
|
|
271
|
+
- Optional PostgreSQL storage.
|
|
272
|
+
- Retention policies.
|
|
273
|
+
- Audit package bundles.
|
|
274
|
+
- Provenance attestations.
|
|
275
|
+
- Organization-specific event profiles.
|
|
276
|
+
- SIEM exporters.
|
|
277
|
+
|
|
278
|
+
1.0 considerations:
|
|
279
|
+
|
|
280
|
+
- Stable schema.
|
|
281
|
+
- Compatibility policy.
|
|
282
|
+
- Formal canonicalization profile.
|
|
283
|
+
- Migration policy.
|
|
284
|
+
- Interoperability test suite.
|
|
285
|
+
- Independent security review.
|
|
286
|
+
|
|
287
|
+
## Contributing
|
|
288
|
+
|
|
289
|
+
Use the development commands in `docs/getting-started.md`. Keep claims
|
|
290
|
+
verifiable and do not commit secrets, private keys, local audit logs, databases,
|
|
291
|
+
or generated distribution artifacts.
|
|
292
|
+
|
|
293
|
+
## License
|
|
294
|
+
|
|
295
|
+
MIT.
|
|
296
|
+
|
|
297
|
+
## Author
|
|
298
|
+
|
|
299
|
+
sekacorn
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
# AIAuditLog
|
|
2
|
+
|
|
3
|
+
AIAuditLog provides portable, privacy-aware, tamper-evident evidence for AI
|
|
4
|
+
models, agents, tools, policies, reviews, and workflow outcomes.
|
|
5
|
+
|
|
6
|
+
This is an alpha release candidate for `0.1.0a3`. It is ready for public alpha
|
|
7
|
+
release with documented limitations, not production certification.
|
|
8
|
+
|
|
9
|
+
## Why AI Audit Logs Are Different
|
|
10
|
+
|
|
11
|
+
Ordinary application logs usually explain what software printed while it ran.
|
|
12
|
+
AI audit evidence must also preserve model choices, tool access, policy
|
|
13
|
+
decisions, human approvals, data references, redaction decisions, and workflow
|
|
14
|
+
outcomes in a vendor-neutral format that survives framework and provider
|
|
15
|
+
changes.
|
|
16
|
+
|
|
17
|
+
## Problem Statement
|
|
18
|
+
|
|
19
|
+
Organizations need inspectable evidence of what an AI system did, why it acted,
|
|
20
|
+
which models and policies were involved, what data and tools were accessed, and
|
|
21
|
+
what outcome occurred. AIAuditLog keeps that evidence local-first, append
|
|
22
|
+
oriented, deterministic, and suitable for CI review.
|
|
23
|
+
|
|
24
|
+
## Ecosystem Position
|
|
25
|
+
|
|
26
|
+
AIAuditLog is project six in the sekacorn AI infrastructure roadmap. It is
|
|
27
|
+
designed for future optional integration with Forge, PrivateAIStack,
|
|
28
|
+
ModelSwapBench, OpenOntologyLite, AgentPolicyPack, and OpenAIMeter. The first
|
|
29
|
+
alpha works independently and offline.
|
|
30
|
+
|
|
31
|
+
## Core Capabilities
|
|
32
|
+
|
|
33
|
+
- Versioned JSON event envelope and JSON Schema export.
|
|
34
|
+
- Typed Python models for AI, agent, tool, policy, ontology, and benchmark context.
|
|
35
|
+
- RFC8785-backed canonical JSON after AIAuditLog value normalization.
|
|
36
|
+
- SHA-256 event digests.
|
|
37
|
+
- Optional hash-chain metadata for tamper evidence.
|
|
38
|
+
- Checkpoints, optional Ed25519 checkpoint signatures, and signature policies.
|
|
39
|
+
- JSONL storage and SQLite indexing.
|
|
40
|
+
- Stream rotation, lock-file guarded appends, compressed exports, and schema migration helpers.
|
|
41
|
+
- Privacy modes, deterministic redaction, secret-key filtering, classification redaction, and CSV-safe export.
|
|
42
|
+
- CLI and Python API.
|
|
43
|
+
- Neutral adapter protocols for future ecosystem packages.
|
|
44
|
+
|
|
45
|
+
## Event Architecture
|
|
46
|
+
|
|
47
|
+
Each event contains `schema_version`, `event_id`, `event_type`, UTC
|
|
48
|
+
`event_time`, UTC `recorded_time`, `source`, `actor`, `outcome`, `data`,
|
|
49
|
+
optional context, and `integrity`. Core event types cover system, agent, model,
|
|
50
|
+
tool, data, retrieval, policy, review, security, evaluation, benchmark, and
|
|
51
|
+
audit-log lifecycle categories. Custom event types must be namespaced and may
|
|
52
|
+
not collide with reserved core namespaces.
|
|
53
|
+
|
|
54
|
+
## Installation
|
|
55
|
+
|
|
56
|
+
```powershell
|
|
57
|
+
python -m pip install aiauditlog
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
For development:
|
|
61
|
+
|
|
62
|
+
```powershell
|
|
63
|
+
python -m pip install -e ".[dev]"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Quick Start
|
|
67
|
+
|
|
68
|
+
```powershell
|
|
69
|
+
aiaudit validate examples/basic/event.json
|
|
70
|
+
aiaudit append build/audit.jsonl --event examples/basic/event.json
|
|
71
|
+
aiaudit verify build/audit.jsonl
|
|
72
|
+
aiaudit summarize build/audit.jsonl
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## JSON Event Example
|
|
76
|
+
|
|
77
|
+
See `examples/basic/event.json` for a complete model invocation event. Prompts
|
|
78
|
+
and responses are not stored by default; use hashes, references, counts, and
|
|
79
|
+
explicitly configured safe excerpts.
|
|
80
|
+
|
|
81
|
+
## Recorder Example
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
from ai_audit_log import AuditRecorder, EventBuilder, JsonlStore, Outcome, Source
|
|
85
|
+
from ai_audit_log.models import Actor
|
|
86
|
+
|
|
87
|
+
builder = EventBuilder(
|
|
88
|
+
source=Source(service="claims-agent"),
|
|
89
|
+
actor=Actor(actor_id="agent-17", actor_type="ai_agent"),
|
|
90
|
+
)
|
|
91
|
+
recorder = AuditRecorder(builder=builder, store=JsonlStore("build/audit.jsonl"))
|
|
92
|
+
recorder.record(
|
|
93
|
+
event_type="model.invocation.completed",
|
|
94
|
+
outcome=Outcome(status="success", code="COMPLETED"),
|
|
95
|
+
data={"provider": "example", "model_name": "example-model"},
|
|
96
|
+
)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Chain Verification
|
|
100
|
+
|
|
101
|
+
```powershell
|
|
102
|
+
aiaudit verify build/audit.jsonl
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Hash chaining is tamper-evident, not immutable. An attacker who can rewrite an
|
|
106
|
+
entire unsigned log can recompute the chain.
|
|
107
|
+
|
|
108
|
+
## Privacy Modes
|
|
109
|
+
|
|
110
|
+
The default mode is `minimal`: identifiers, metadata, hashes, counts, outcomes,
|
|
111
|
+
and policy evidence are preserved, while prompts, responses, and common secret
|
|
112
|
+
keys are redacted. `balanced` may keep short configured excerpts.
|
|
113
|
+
`full-content` requires explicit opt-in and can expose sensitive data.
|
|
114
|
+
|
|
115
|
+
## Checkpoints And Signatures
|
|
116
|
+
|
|
117
|
+
Checkpoints summarize stream ID, event count, terminal digest, and checkpoint
|
|
118
|
+
digest. Ed25519 signatures authenticate the checkpoint bytes to a public key,
|
|
119
|
+
and checkpoint signature policies can require allowed key IDs, fingerprints, and
|
|
120
|
+
minimum signature counts. Signatures do not prove real-world actor identity,
|
|
121
|
+
legal non-repudiation, or correct key custody.
|
|
122
|
+
|
|
123
|
+
```powershell
|
|
124
|
+
aiaudit checkpoint create build/audit.jsonl --output build/checkpoint.json
|
|
125
|
+
aiaudit key generate --private-key build/development-private.pem --public-key build/development-public.pem
|
|
126
|
+
aiaudit sign build/checkpoint.json --private-key build/development-private.pem --key-id development-key
|
|
127
|
+
aiaudit signature verify build/checkpoint.json --public-key build/development-public.pem
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Never commit generated private keys.
|
|
131
|
+
|
|
132
|
+
## CLI Examples
|
|
133
|
+
|
|
134
|
+
```powershell
|
|
135
|
+
aiaudit inspect examples/basic/event.json
|
|
136
|
+
aiaudit query build/audit.jsonl --event-type model.invocation.completed
|
|
137
|
+
aiaudit export build/audit.jsonl --format markdown --output build/audit-report.md --compress
|
|
138
|
+
aiaudit redact build/audit.jsonl --profile examples/privacy/minimal.yaml --output build/audit-redacted.jsonl
|
|
139
|
+
aiaudit migrate examples/basic/legacy-event.json --output build/migrated-event.json
|
|
140
|
+
aiaudit rotate build/audit.jsonl
|
|
141
|
+
aiaudit schema list
|
|
142
|
+
aiaudit schema export --output build/schemas
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Storage
|
|
146
|
+
|
|
147
|
+
JSONL is the canonical local stream format. SQLite indexing is optional and is
|
|
148
|
+
not tamper-proof; chain verification recalculates event digests from stored
|
|
149
|
+
events.
|
|
150
|
+
|
|
151
|
+
## Adapters
|
|
152
|
+
|
|
153
|
+
The package includes neutral protocols for framework, policy, ontology, and
|
|
154
|
+
benchmark adapters. No external ecosystem package is required in core.
|
|
155
|
+
|
|
156
|
+
## Security Model
|
|
157
|
+
|
|
158
|
+
AIAuditLog distinguishes application logs, telemetry, audit evidence,
|
|
159
|
+
cryptographic integrity, authenticity, non-repudiation, and legal
|
|
160
|
+
admissibility. It provides local tamper evidence and optional checkpoint
|
|
161
|
+
signatures. It does not provide immutable storage, identity proofing, legal
|
|
162
|
+
certification, a SIEM, or policy enforcement.
|
|
163
|
+
|
|
164
|
+
## Threat Model And Limitations
|
|
165
|
+
|
|
166
|
+
- Hash chaining is tamper-evident, not immutable.
|
|
167
|
+
- An attacker who can rewrite the entire log may recompute an unsigned chain.
|
|
168
|
+
- Signatures depend on secure key custody.
|
|
169
|
+
- The package does not establish real-world actor identity.
|
|
170
|
+
- Timestamps depend on system clocks.
|
|
171
|
+
- Local storage can be deleted.
|
|
172
|
+
- SQLite is not tamper-proof.
|
|
173
|
+
- Full-content logging may expose sensitive data.
|
|
174
|
+
- Redaction and secret detection are heuristic and not perfect.
|
|
175
|
+
- Adapters depend on external framework APIs.
|
|
176
|
+
- Event completeness depends on correct instrumentation.
|
|
177
|
+
- Missing events cannot always be distinguished from actions that never occurred.
|
|
178
|
+
- Audit records do not guarantee model correctness.
|
|
179
|
+
- Audit records do not enforce policy.
|
|
180
|
+
- Compliance mappings are informational.
|
|
181
|
+
- This project is not legal advice.
|
|
182
|
+
- The schema may evolve before version 1.0.
|
|
183
|
+
- External anchoring and trusted timestamping are not included in this alpha.
|
|
184
|
+
- Concurrent multi-process writing has documented limitations unless explicitly tested.
|
|
185
|
+
|
|
186
|
+
## Interoperability
|
|
187
|
+
|
|
188
|
+
Canonical JSON serialization uses the maintained `rfc8785` package after
|
|
189
|
+
AIAuditLog normalizes datetimes, Decimals, bytes, and model objects. Timestamps
|
|
190
|
+
are RFC 3339-compatible UTC strings. Trace and span fields can carry W3C Trace
|
|
191
|
+
Context or OpenTelemetry identifiers, and helper functions can parse and emit
|
|
192
|
+
`traceparent` values. CloudEvents concepts influenced envelope naming, but this
|
|
193
|
+
package does not claim CloudEvents compliance.
|
|
194
|
+
|
|
195
|
+
## Roadmap
|
|
196
|
+
|
|
197
|
+
Implemented in 0.1.0a2:
|
|
198
|
+
|
|
199
|
+
- RFC8785-backed canonicalization with an RFC8785 sample vector.
|
|
200
|
+
- Signed checkpoint policies.
|
|
201
|
+
- Stream rotation.
|
|
202
|
+
- Deterministic gzip exports.
|
|
203
|
+
- Richer privacy profiles.
|
|
204
|
+
- Lock-file guarded appends.
|
|
205
|
+
- Conservative schema migration helpers.
|
|
206
|
+
|
|
207
|
+
Implemented in 0.1.0a3:
|
|
208
|
+
|
|
209
|
+
- Neutral Forge-like agent step adapter.
|
|
210
|
+
- Neutral AgentPolicyPack-like policy decision adapter.
|
|
211
|
+
- Neutral ModelSwapBench-like benchmark context adapter.
|
|
212
|
+
- Neutral OpenOntologyLite-like ontology context adapter.
|
|
213
|
+
- Neutral PrivateAIStack metadata adapter.
|
|
214
|
+
- OpenTelemetry/W3C Trace Context helpers.
|
|
215
|
+
|
|
216
|
+
The 0.1.0a3 adapters intentionally use plain dictionaries and are not claimed as
|
|
217
|
+
externally tested against sibling packages.
|
|
218
|
+
|
|
219
|
+
Next candidates for 0.1.0a4:
|
|
220
|
+
|
|
221
|
+
- Broader export test coverage for JSON, JSONL, CSV, Markdown, and compressed outputs.
|
|
222
|
+
- Signed stream manifests.
|
|
223
|
+
- Stronger rotation manifests and rotation verification.
|
|
224
|
+
- More complete schema migration fixtures.
|
|
225
|
+
- Optional dependency-license report generation.
|
|
226
|
+
- Improved concurrent-writer stress tests.
|
|
227
|
+
|
|
228
|
+
0.2 candidates:
|
|
229
|
+
|
|
230
|
+
- External checkpoint anchoring.
|
|
231
|
+
- Optional PostgreSQL storage.
|
|
232
|
+
- Retention policies.
|
|
233
|
+
- Audit package bundles.
|
|
234
|
+
- Provenance attestations.
|
|
235
|
+
- Organization-specific event profiles.
|
|
236
|
+
- SIEM exporters.
|
|
237
|
+
|
|
238
|
+
1.0 considerations:
|
|
239
|
+
|
|
240
|
+
- Stable schema.
|
|
241
|
+
- Compatibility policy.
|
|
242
|
+
- Formal canonicalization profile.
|
|
243
|
+
- Migration policy.
|
|
244
|
+
- Interoperability test suite.
|
|
245
|
+
- Independent security review.
|
|
246
|
+
|
|
247
|
+
## Contributing
|
|
248
|
+
|
|
249
|
+
Use the development commands in `docs/getting-started.md`. Keep claims
|
|
250
|
+
verifiable and do not commit secrets, private keys, local audit logs, databases,
|
|
251
|
+
or generated distribution artifacts.
|
|
252
|
+
|
|
253
|
+
## License
|
|
254
|
+
|
|
255
|
+
MIT.
|
|
256
|
+
|
|
257
|
+
## Author
|
|
258
|
+
|
|
259
|
+
sekacorn
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Python API
|
|
2
|
+
|
|
3
|
+
Primary imports:
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
from ai_audit_log import AuditEvent, AuditRecorder, EventBuilder, JsonlStore, Outcome, Source
|
|
7
|
+
from ai_audit_log.models import Actor
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Use `EventBuilder` to create validated privacy-filtered events, `AuditRecorder`
|
|
11
|
+
to append chained events, `JsonlStore` for JSONL streams, `SQLiteIndex` for
|
|
12
|
+
query indexing, `ChainVerifier` for integrity checks, and `Checkpoint` helpers
|
|
13
|
+
for stream summaries.
|
|
14
|
+
|
|
15
|
+
Additional alpha helpers:
|
|
16
|
+
|
|
17
|
+
- `ai_audit_log.rotation` for stream rotation policies.
|
|
18
|
+
- `ai_audit_log.compression` for deterministic gzip files.
|
|
19
|
+
- `ai_audit_log.migration` for conservative early-schema migration.
|
|
20
|
+
- `ai_audit_log.checkpoint_policy` for signed checkpoint policy checks.
|
|
21
|
+
- `ai_audit_log.otel` for W3C Trace Context correlation helpers.
|
|
22
|
+
- `ai_audit_log.ecosystem` for neutral dictionary adapters.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# CLI
|
|
2
|
+
|
|
3
|
+
Commands:
|
|
4
|
+
|
|
5
|
+
- `validate EVENT`: validate one event JSON file.
|
|
6
|
+
- `inspect EVENT`: print a compact JSON inspection.
|
|
7
|
+
- `append LOG --event EVENT`: append with chain integrity.
|
|
8
|
+
- `append LOG --event EVENT --lock`: append with a simple lock file.
|
|
9
|
+
- `verify LOG`: verify a chain.
|
|
10
|
+
- `query LOG`: filter by event type, status, stream, and limit.
|
|
11
|
+
- `summarize LOG`: summarize event types and outcomes.
|
|
12
|
+
- `checkpoint create LOG --output PATH`: create a checkpoint.
|
|
13
|
+
- `checkpoint verify CHECKPOINT --log LOG`: verify a checkpoint.
|
|
14
|
+
- `export LOG --format jsonl|json|csv|markdown --output PATH --compress`: export events, optionally with gzip.
|
|
15
|
+
- `redact LOG --profile PROFILE --output PATH`: write redacted JSONL.
|
|
16
|
+
- `compress PATH`: create a deterministic gzip copy.
|
|
17
|
+
- `rotate LOG`: rotate a stream to the next numbered path.
|
|
18
|
+
- `migrate EVENT --output PATH`: migrate an early alpha event document.
|
|
19
|
+
- `schema list`: list schemas.
|
|
20
|
+
- `schema export --output DIR`: write JSON Schema files.
|
|
21
|
+
- `key generate`: create an Ed25519 development key pair.
|
|
22
|
+
- `key generate --force`: overwrite existing key files.
|
|
23
|
+
- `sign CHECKPOINT`: sign a checkpoint in place.
|
|
24
|
+
- `signature verify CHECKPOINT`: verify checkpoint signatures.
|
|
25
|
+
|
|
26
|
+
Do not commit private keys generated by `key generate`.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Event Envelope
|
|
2
|
+
|
|
3
|
+
Required fields are `schema_version`, `event_id`, `event_type`, `event_time`,
|
|
4
|
+
`recorded_time`, `source`, `actor`, `outcome`, and `data`. Chained events also
|
|
5
|
+
include `integrity.stream_id`, `integrity.sequence`,
|
|
6
|
+
`integrity.previous_event_digest`, and `integrity.event_digest`.
|
|
7
|
+
|
|
8
|
+
Event IDs use UUID strings. Python 3.11 lacks a standard UUIDv7 generator, so
|
|
9
|
+
0.1.0a1 uses UUIDv4 for generated IDs and documents that generated IDs are
|
|
10
|
+
unique but not time-sortable. Externally supplied UUIDs are preserved.
|
|
11
|
+
|
|
12
|
+
Timestamps must be timezone-aware and are serialized as UTC RFC
|
|
13
|
+
3339-compatible strings with a `Z` suffix. Timestamps are not an ordering or
|
|
14
|
+
integrity mechanism.
|
|
15
|
+
|
|
16
|
+
Sequence numbers begin at `1`, increment by one within a stream, are included in
|
|
17
|
+
event digests, and are checked during chain verification.
|