λgitsite

~ober/jerboa-awk

Imported from ~/mine/jerboa-awk

download snapshot

about

# jerboa-awk

`jawk` is an AWK interpreter implemented in Jerboa Scheme.

## Build and Test

```sh
make verify
make release-evidence
```

`make verify` runs the source security gate, import check, parser regression
tests, deterministic parser corpus evidence, native binary build, CLI smoke
tests, and secure-default policy tests. `make release-evidence` also records
SBOM/toolchain evidence and a two-pass clean-build reproducibility report for
the generated `jawk` binary, repeated parser corpus output, and target proof
status.

## Secure Defaults

AWK programs are treated as hostile input unless the caller explicitly opts into
legacy AWK capabilities:

- `JAWK_ALLOW_SYSTEM=1` enables `system()` and pipe redirections.
- `JAWK_ALLOW_FILE_IO=1` enables script-driven `print > file` and
  `getline < file` I/O. CLI input files and `-f` program files remain supported.
- `JAWK_EXPOSE_ENVIRON=1` exposes a small allowlist of process environment
  variables through `ENVIRON`; by default `ENVIRON` is empty.
- `JAWK_MAX_PROGRAM_CHARS` caps program text, default 1 MiB.
- `JAWK_MAX_RECORD_CHARS` caps input records, default 1 MiB.
- `JAWK_MAX_REGEX_CACHE_ENTRIES` bounds each evaluation's dynamic-regex LRU,
  default 64. Regex, range-pattern, random-number, and multi-character
  record-buffer state is never shared between evaluations. Transient caches
  and buffers are cleared during evaluation cleanup.

Library embeddings must create an independent environment with
`make-initial-env` for each evaluation and use it only from the thread that
created it. Runtime entry points reject cross-thread reuse. Concurrent
evaluations are supported when each worker creates and owns its own environment.

Generated `jawk` binaries and native build artifacts are ignored and must not be
tracked.

Production support also requires a reviewed `JAWK_TARGET_PROOF_FILE` with the
markers documented in `docs/release-evidence.md`. `JAWK_REQUIRE_TARGET_PROOF=1`
fails closed when that target proof is missing or incomplete.

## Example

```sh
echo "hello world" | ./jawk '{print $1}'
echo "a,b,c" | ./jawk -F, '{print $2}'
```

## Security Docs

- `SECURITY.md`
- `docs/threat-model.md`
- `docs/parser-hardening.md`
- `docs/release-evidence.md`

recent commits