audit

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 21, 2026 License: MIT Imports: 1 Imported by: 0

README

audit

A company-wide audit trail: one record format, one write path, one immutable store, and projections for security, billing, history and regulatory evidence.

Start here

you want to read
see how it fits together Architecture — the parts, what each holds, the life of one record
run it in a cluster Deploying — what to prepare, the chart, a diagram, how to check it works
connect an application to an installation Integrating — the catalogue, the emitter, the audit page in your console
record what your application does Emitting records — the catalogue, registering it, the Go emitter; examples/emit
carry the trail inside your application: its own writer, its own query API Embedding — writer.Open, query.New; examples/embed
search and read the trail, or audit it Reading the trail — access, the API, Go and TypeScript clients, audit verify; examples/read
understand why it is built this way why, then concepts, then the decisions

Status

part state
Record, catalogues, presets, audit validate / check-emitters built
Go emitter: block, outbox and best-effort delivery; Connect and JetStream sinks built
Writer: split per profile, pseudonyms, Object Lock, index, dead letters, legal holds built
Pseudonymisation keys: local (root + directory) or OpenBAO transit built; AWS KMS envelope designed (decision), not built
Digest chain and audit verify; signing with a key file, AWS KMS or OpenBAO transit built
Query service: search, facets, get with provenance, export, tail, resolve; JWT sign-in with grants built
Embedding: the writer and the query service as Go libraries (writer, query) built
Helm chart: writer, registry, query service, digest / verify / clock / purge jobs built
TypeScript @truvity/audit: query client, qualifier box, catalogue sentences, React hooks and an MUI view to embed built, not yet published
TypeScript emitter; a standalone console designed, not built — applications host the page in their own console
Metering projection not yet
A published release not yet — build the images with just snapshot

What it is

  • A canonical record described in Protocol Buffers, with predefined extension slots described in JSON Schema so applications add their own data without changing the core.
  • An action catalogue per application: which actions exist, what they carry, which profiles they belong to, how they read as a sentence, and how they meter.
  • A split writer that turns each record into one copy per profile, each in its own Object-Locked S3 prefix with its own field allow-list, identity treatment and retention. Profiles are composed from framework presets shipped in presets/.
  • A query service with faceted search, cursor pagination, export and a tail cursor, behind pluggable authentication and authorization.
  • A viewer: an embeddable React package and a standalone console.
  • A digest chain and a verify command so an auditor can prove nothing was removed or altered without trusting the operator.
  • Metering projections so the same records feed usage-based billing.

What it is not

  • Not an application log pipeline. Application logs keep flowing through the observability stack; this component records what happened, who did it, to what, with what outcome, and keeps it for as long as a framework requires.
  • Not a SIEM. It exports to one.
  • Not a wallet transaction log. A digital-identity wallet's own log lives on the user's device and is invisible to the provider by law; this component only ever sees operational events with pseudonymous subjects.

Layout

examples/           an application that emits, a program that reads — compiled in CI
proto/audit/v1/     record, sink and query contracts (canonical schema)
schemas/            JSON Schema for catalogues, presets and the annotation vocabulary
presets/            one file per framework: required fields, retention, citations
catalogue/          the common catalogue (the component's own meta-events)
docs/guides/        deploying, emitting, reading: start here
docs/why.md         what this is and is not
docs/concepts.md    record, catalogue, slots, profiles, presets, prefixes
docs/design/        pipeline, split writer, search, authz, integrity, metering, viewer
docs/decisions/     architecture decision records
docs/research/      the surveys the design rests on, with sources
docs/reference/     record, catalogue, presets, API, configuration
docs/operations/    S3 guide, key custody, verification, runbook
docs/development/   package layout and build order for implementers
charts/audit/       writer, registry and jobs, deployable; refuses what the binaries would

Licence

MIT. See LICENSE.

Documentation

Overview

Package audit carries the files this repository publishes as data: the framework presets, the meta-schemas that govern catalogues and presets, and the common catalogue of the component's own events.

They are embedded so that a deployment gets them from the binary it already runs, rather than from files it has to ship and keep in step.

Index

Constants

This section is empty.

Variables

View Source 
var Catalogue embed.FS

Catalogue is the common catalogue: the component's own meta-events, which every deployment carries.

View Source 
var Generated embed.FS

Generated holds what this build published for readers outside Go: the record's JSON Schema, with the proto's comments carried as descriptions. The writer puts a copy of it in the archive beside the records it describes.

View Source 
var Presets embed.FS

Presets are the framework presets under presets/.

View Source 
var Proto embed.FS

Proto is the schema of record itself. The writer copies the proto of a record's major beside the record's JSON Schema on first use, so the archive keeps the meaning of every field and not only its shape.

View Source 
var Schemas embed.FS

Schemas are the meta-schemas under schemas/: catalogue, preset, extension.

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package auth is where a deployment plugs in who is asking and what they may see.
 Package auth is where a deployment plugs in who is asking and what they may see.
Package catalogue reads and validates the action catalogues that describe what a source emits.
 Package catalogue reads and validates the action catalogues that describe what a source emits.
cmd
audit command
Command audit is the tool that holds a deployment to the contracts this repository publishes: it validates catalogues and presets, explains what a profile keeps, and checks that the code and the catalogue still agree.
 Command audit is the tool that holds a deployment to the contracts this repository publishes: it validates catalogues and presets, explains what a profile keeps, and checks that the code and the catalogue still agree.
audit-query command
Command audit-query answers questions about what was written.
 Command audit-query answers questions about what was written.
audit-registry command
Command audit-registry keeps the catalogues a deployment has registered.
 Command audit-registry keeps the catalogues a deployment has registered.
audit-writer command
Command audit-writer takes records and puts the copies their profiles keep.
 Command audit-writer takes records and puts the copies their profiles keep.
protoc-gen-audit-jsonschema command
Command protoc-gen-audit-jsonschema is the buf plugin that writes the record's JSON Schema.
 Command protoc-gen-audit-jsonschema is the buf plugin that writes the record's JSON Schema.
deploy
pulumi module
Package emit is what an application imports to record what it did.
 Package emit is what an application imports to record what it did.
examples
embed command
Command embed is an example application that carries its own audit trail: it embeds the writer, so its records go straight into the locked bucket with no writer or stream to run beside it, and it serves the query API behind its own sign-in, so its console can read the trail with the standard viewer.
 Command embed is an example application that carries its own audit trail: it embeds the writer, so its records go straight into the locked bucket with no writer or stream to run beside it, and it serves the query API behind its own sign-in, so its console can read the trail with the standard viewer.
emit command
Command emit is an example application that records what it does into the audit trail.
 Command emit is an example application that records what it does into the audit trail.
read command
Command read is an example of reading the audit trail from Go: a search, paged to the end with its cursor, and one record read with where it came from.
 Command read is an example of reading the audit trail from Go: a search, paged to the end with its cursor, and one record read with where it came from.
gen
audit/v1
audit/v1/auditv1connect
Package index is the projection a search reads.
 Package index is the projection a search reads.
indextest
Package indextest is the one corpus every searcher is asked about.
 Package indextest is the one corpus every searcher is asked about.
postgres
Package postgres is the default index and the shared deduplication store.
 Package postgres is the default index and the shared deduplication store.
s3scan
Package s3scan answers queries by reading the archive, with no index at all.
 Package s3scan answers queries by reading the archive, with no index at all.
internal
authtest
Package authtest is an identity provider for tests: a discovery document and a key set served over a real listener, so the code under test runs its actual discovery and key fetch rather than being handed a key.
 Package authtest is an identity provider for tests: a discovery document and a key set served over a real listener, so the code under test runs its actual discovery and key fetch rather than being handed a key.
cli
Package cli is the implementation behind cmd/audit.
 Package cli is the implementation behind cmd/audit.
clock
Package clock measures how far this machine's clock is from UTC.
 Package clock measures how far this machine's clock is from UTC.
corpus
Package corpus reads the example records in testdata/records, for tests that hold a transport or an encoder to them.
 Package corpus reads the example records in testdata/records, for tests that hold a transport or an encoder to them.
digest
Package digest builds and checks the chain that makes the archive tamper-evident.
 Package digest builds and checks the chain that makes the archive tamper-evident.
hold
Package hold places and releases legal holds over the archive.
 Package hold places and releases legal holds over the archive.
identity
Package identity is the way back from a pseudonym to the person, for the cases the law requires and only for them.
 Package identity is the way back from a pseudonym to the person, for the cases the law requires and only for them.
metaschema
Package metaschema validates a document against one of the meta-schemas this repository publishes: the catalogue format, the preset format, and the constraints every extension-slot schema must satisfy.
 Package metaschema validates a document against one of the meta-schemas this repository publishes: the catalogue format, the preset format, and the constraints every extension-slot schema must satisfy.
pgtest
Package pgtest gives a test its own Postgres schema.
 Package pgtest gives a test its own Postgres schema.
query
Package query is the read service: it turns a request into a closed query, narrows it to what the caller was granted, asks a searcher, and records that the read happened.
 Package query is the read service: it turns a request into a closed query, narrows it to what the caller was granted, asks a searcher, and records that the read happened.
registry
Package registry holds the catalogues a deployment has registered.
 Package registry holds the catalogues a deployment has registered.
s3test
Package s3test gives a test a real S3 to walk.
 Package s3test gives a test a real S3 to walk.
schemagen
Package schemagen turns the record's protobuf descriptor into a JSON Schema of the form this project writes.
 Package schemagen turns the record's protobuf descriptor into a JSON Schema of the form this project writes.
telemetry
Package telemetry is the OpenTelemetry metrics this repository's processes publish.
 Package telemetry is the OpenTelemetry metrics this repository's processes publish.
writer
Package writer turns records into the copies the profiles keep, and puts those copies where they are kept.
 Package writer turns records into the copies the profiles keep, and puts those copies where they are kept.
Package keys holds the two kinds of key this system needs and the interfaces a deployment plugs its own behind.
 Package keys holds the two kinds of key this system needs and the interfaces a deployment plugs its own behind.
Package preset reads the framework presets and composes them into profiles.
 Package preset reads the framework presets and composes them into profiles.
Package query is the query service as a library: search, facets, get, export, tail and resolve over what the writer wrote, behind the grants a caller holds, with every read recorded in the trail it reads.
 Package query is the query service as a library: search, facets, get, export, tail and resolve over what the writer wrote, behind the grants a caller holds, with every read recorded in the trail it reads.
Package record is the canonical audit record: the generated protobuf type plus the rules the type alone cannot express — identifiers, bounds, the negative list, and the canonical JSON form that every hash is taken over.
 Package record is the canonical audit record: the generated protobuf type plus the rules the type alone cannot express — identifiers, bounds, the negative list, and the canonical JSON form that every hash is taken over.
sdk module
Package sink is the write contract, and it is the same contract at every hop.
 Package sink is the write contract, and it is the same contract at every hop.
natssink
Package natssink publishes records to a NATS JetStream stream, and consumes them again on the other side.
 Package natssink publishes records to a NATS JetStream stream, and consumes them again on the other side.
Package store is the object store the archive lives in.
 Package store is the object store the archive lives in.
s3store
Package s3store keeps the archive in an S3 bucket.
 Package s3store keeps the archive in an S3 bucket.
storetest
Package storetest holds the store a test writes to.
 Package storetest holds the store a test writes to.
Package wire is how this repository's services speak JSON.
 Package wire is how this repository's services speak JSON.
Package writer is the audit writer as a library: the thing that takes records, splits them into the copies their profiles keep, pseudonymises, and puts them into the locked archive.
 Package writer is the audit writer as a library: the thing that takes records, splits them into the copies their profiles keep, pseudonymises, and puts them into the locked archive.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.