Security hardening and release readiness
Jaime Fournier <jaimef@linbsd.org>
d99bc7d616aa03748d077c7216b29c43fb897bb0
diff --git a/.build.yml b/.build.yml
new file mode 100644
index 0000000..1f58732
--- /dev/null
+++ b/.build.yml
@@ -0,0 +1,15 @@
+image: ubuntu/latest
+packages:
+ - git
+ - make
+ - gcc
+ - curl
+ - ca-certificates
+ - ripgrep
+tasks:
+ - verify: |
+ cd jerboa-asm
+ make verify
+ - release-evidence: |
+ cd jerboa-asm
+ make release-evidence
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..b695be9
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,33 @@
+name: CI
+
+on:
+ push:
+ branches: [main, master]
+ pull_request:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ verify:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install build tools
+ run: sudo apt-get update && sudo apt-get install -y build-essential curl ca-certificates ripgrep
+
+ - name: Install jerbuild
+ run: |
+ set -eux
+ curl -fsSL "https://github.com/jerboa-lang/jerboa/releases/download/${JERBOA_VERSION}/jerbuild-linux-x86_64" -o /usr/local/bin/jerbuild
+ chmod +x /usr/local/bin/jerbuild
+ env:
+ JERBOA_VERSION: v0.2.3
+
+ - name: Verify
+ run: make verify
+
+ - name: Release evidence
+ run: make release-evidence
diff --git a/.github/workflows/security-baseline.yml b/.github/workflows/security-baseline.yml
new file mode 100644
index 0000000..4d15e85
--- /dev/null
+++ b/.github/workflows/security-baseline.yml
@@ -0,0 +1,22 @@
+name: Security Baseline
+
+on:
+ push:
+ branches: [main, master]
+ pull_request:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ baseline:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install scanner tools
+ run: sudo apt-get update && sudo apt-get install -y ripgrep
+
+ - name: Security baseline
+ run: scripts/security-check.sh
diff --git a/.gitignore b/.gitignore
index a8e6f33..310f23a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,9 @@
+/.build/
+/dist/
+/jasm
+*.a
+*.boot
+*.o
*.so
*.wpo
*.wp.so
diff --git a/.jerboa/security.json b/.jerboa/security.json
new file mode 100644
index 0000000..ba124bb
--- /dev/null
+++ b/.jerboa/security.json
@@ -0,0 +1,52 @@
+{
+ "name": "jerboa-asm",
+ "classification": "hostile-input parser and CLI",
+ "license": "Apache-2.0",
+ "network": {
+ "runtime": "none",
+ "tests": "none"
+ },
+ "filesystem": {
+ "runtime": "reads user-selected object or raw byte files; writes no output files",
+ "tests": "writes only allowlisted .jasm-* fixture files",
+ "release": "generated native binaries and object files must be ignored and untracked"
+ },
+ "resource_limits": {
+ "JASM_MAX_INPUT_BYTES": "maximum object/raw file read size; default 67108864",
+ "JASM_MAX_HEX_CHARS": "maximum CLI hex string length before cleanup; default 16777216"
+ },
+ "ffi": {
+ "runtime": "none in repository source",
+ "build": "jerbuild emits native artifacts from Jerboa source"
+ },
+ "targetEvidence": {
+ "script": "scripts/target-evidence.sh",
+ "optionalProofFileEnv": "JASM_TARGET_PROOF_FILE",
+ "requiredProofEnv": "JASM_REQUIRE_TARGET_PROOF",
+ "maxProofBytes": 65536,
+ "targetProofStatus": "target_asm_proof_status",
+ "productionStatus": "production_asm_status",
+ "sensitiveArtifactPolicy": "no-object-inputs-output-captures-private-paths-or-host-data",
+ "requiredMarkers": [
+ "long_object_parser_corpus_status=reviewed",
+ "external_parser_review_status=reviewed",
+ "external_disassembler_parity_status=reviewed",
+ "cross_tool_corpus_status=reviewed",
+ "object_format_review_status=reviewed",
+ "resource_limit_review_status=reviewed",
+ "sensitive_artifact_policy=no-object-inputs-output-captures-private-paths-or-host-data"
+ ]
+ },
+ "release_gates": [
+ "make security",
+ "make test",
+ "make test-binary",
+ "make verify",
+ "make target-evidence",
+ "make release-evidence"
+ ],
+ "accepted_risks": [
+ "The disassembler is intentionally incomplete; unsupported instructions may render as bytes or errors.",
+ "Parser coverage is regression-based in this repository; external fuzzing should run before broad hostile-corpus exposure."
+ ]
+}
diff --git a/LICENSE b/LICENSE
index c3decd7..261eeb9 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,201 @@
-SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
-Copyright 2026 jasm contributors
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-Licensed under the Apache License, Version 2.0 with LLVM Exceptions. See
-https://llvm.org/LICENSE.txt for the license text.
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/Makefile b/Makefile
index 1ced032..06a5999 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,12 @@
-# jerbuild bundles Chez Scheme + the jerboa stdlib under ~/.cache/jerbuild/,
-# so building jasm needs only `jerbuild` + a C compiler — no jerboa source
-# checkout and no separately-built Chez.
-JERBUILD ?= jerbuild
+JERBOA_VERSION ?= v0.2.3
+JERBOA_TOOL_DIR ?= ../jerboa/dist
+ifeq ($(origin JERBUILD),undefined)
+ifneq ($(wildcard $(JERBOA_TOOL_DIR)/jerbuild),)
+JERBUILD := $(JERBOA_TOOL_DIR)/jerbuild
+else
+JERBUILD := jerbuild
+endif
+endif
JH := $(shell $(JERBUILD) --jerboa-home 2>/dev/null)
ifeq ($(JH),)
$(error jerbuild not found on PATH (or '$(JERBUILD) --jerboa-home' failed). Install jerbuild, or set JERBUILD=/path/to/jerbuild)
@@ -10,8 +15,12 @@ endif
LIBDIRS := --libdirs lib:$(JH)/lib
JEXEC := $(JERBUILD) exec $(LIBDIRS)
BINARY := jasm
+EVIDENCE_DIR ?= dist/release-evidence
+SBOM_DIR ?= dist/sbom
+REPRO_DIR ?= dist/reproducibility
+TARGET_EVIDENCE_DIR ?= dist/target-evidence
-.PHONY: all build binary run test check test-binary clean
+.PHONY: all build binary run test check test-binary import-check object-fuzz-evidence clean-generated security audit verify sbom reproducibility-report target-evidence release-evidence clean
all: binary
@@ -25,10 +34,63 @@ run: binary
./$(BINARY) $(ARGS)
test:
- $(JEXEC) tests/test-jasm.ss
+ @$(JEXEC) tests/test-jasm.ss
+ @$(JEXEC) tests/test-malformed-objects.ss
check: test
+import-check:
+ @$(JEXEC) support/import-check.ss
+
+object-fuzz-evidence:
+ @$(JEXEC) support/object-fuzz-evidence.ss
+
+clean-generated:
+ rm -f $(BINARY) $(BINARY).wp.so $(BINARY)-main.c petite_boot.h scheme_boot.h program_boot.h .jasm-sample.o .jasm-test-sample.o .jasm-raw.bin
+
+security: clean-generated scripts/security-check.sh import-check
+ scripts/security-check.sh
+
+audit: security
+ @echo "jasm has no vendored native dependency manifest; security script covers source, generated artifacts, and secrets."
+
+target-evidence: scripts/target-evidence.sh
+ @REPO_ROOT=. TARGET_EVIDENCE_DIR="$(TARGET_EVIDENCE_DIR)" sh scripts/target-evidence.sh
+
+verify: audit test object-fuzz-evidence test-binary target-evidence
+
+sbom:
+ REPO_ROOT="$(CURDIR)" SBOM_DIR="$(SBOM_DIR)" JERBUILD="$(JERBUILD)" JERBOA_VERSION="$(JERBOA_VERSION)" sh scripts/sbom.sh
+
+reproducibility-report:
+ REPO_ROOT="$(CURDIR)" REPRO_DIR="$(REPRO_DIR)" MAKE="$(MAKE)" sh scripts/reproducibility-report.sh
+
+release-evidence: verify sbom reproducibility-report
+ rm -rf $(EVIDENCE_DIR)
+ mkdir -p $(EVIDENCE_DIR)
+ rm -f $(BINARY)
+ { git rev-parse HEAD 2>/dev/null || true; } > $(EVIDENCE_DIR)/git-commit.txt
+ git status --short > $(EVIDENCE_DIR)/git-status.txt
+ git diff --stat > $(EVIDENCE_DIR)/diff-stat.txt
+ { printf 'JERBOA_VERSION=%s\n' '$(JERBOA_VERSION)'; "$(JERBUILD)" --version; if "$(JERBUILD)" --jerboa-home >/dev/null 2>&1; then echo "jerboa_home_status=present"; else echo "jerboa_home_status=missing"; fi; uname -srm; env | LC_ALL=C sort | grep -E '^(JASM_MAX_HEX_CHARS|JASM_MAX_INPUT_BYTES)=' || true; } > $(EVIDENCE_DIR)/build-env.txt
+ $(MAKE) security > $(EVIDENCE_DIR)/security.log 2>&1
+ $(MAKE) test > $(EVIDENCE_DIR)/test.log 2>&1
+ $(MAKE) object-fuzz-evidence > $(EVIDENCE_DIR)/object-fuzz-evidence.log 2>&1
+ $(MAKE) test-binary > $(EVIDENCE_DIR)/test-binary.log 2>&1
+ $(MAKE) target-evidence > $(EVIDENCE_DIR)/target-evidence.log 2>&1
+ ./$(BINARY) raw --arch x86-64 --syntax intel --hex '55 48 89 e5 c3' > $(EVIDENCE_DIR)/smoke-x86-64.txt
+ ./$(BINARY) raw --arch aarch64 --hex '20 00 80 d2 c0 03 5f d6' > $(EVIDENCE_DIR)/smoke-aarch64.txt
+ shasum -a 256 ./$(BINARY) > $(EVIDENCE_DIR)/binary-sha256.txt
+ { find . -type f -not -path './.git/*' -not -path './dist/*' -not -path './.build/*' -not -name 'jasm' -not -name '*.so' -not -name '*.wpo' -not -name '*.wp.so' -not -name '*-main.c' -not -name 'petite_boot.h' -not -name 'scheme_boot.h' -not -name 'program_boot.h' | LC_ALL=C sort | while IFS= read -r f; do shasum -a 256 "$$f"; done; } > $(EVIDENCE_DIR)/source-sha256.txt
+ rm -rf $(EVIDENCE_DIR)/sbom $(EVIDENCE_DIR)/reproducibility $(EVIDENCE_DIR)/target-evidence
+ cp -R $(SBOM_DIR) $(EVIDENCE_DIR)/sbom
+ cp -R $(REPRO_DIR) $(EVIDENCE_DIR)/reproducibility
+ cp -R $(TARGET_EVIDENCE_DIR) $(EVIDENCE_DIR)/target-evidence
+ grep -q '^target_evidence_status=present$$' "$(EVIDENCE_DIR)/target-evidence/status.txt"
+ test "$$(grep '^status=' "$(EVIDENCE_DIR)/reproducibility/report.txt" | cut -d= -f2)" = "match"
+ sh scripts/sanitize-evidence.sh "$(EVIDENCE_DIR)"
+ rm -f $(BINARY)
+
# Smoke-test the built binary across architectures.
test-binary: binary
test -x ./$(BINARY)
@@ -38,4 +100,4 @@ test-binary: binary
clean:
rm -f $(BINARY) $(BINARY).wp.so $(BINARY)-main.c petite_boot.h scheme_boot.h program_boot.h .jasm-sample.o .jasm-test-sample.o .jasm-raw.bin
- find . \( -name '*.so' -o -name '*.wpo' \) -print0 | xargs -0 rm -f
+ find . \( -name '*.so' -o -name '*.wpo' -o -name '*.o' \) -print0 | xargs -0 rm -f
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..a15a4e4
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,8 @@
+jerboa-asm
+
+Copyright 2026 jasm contributors.
+
+This repository is licensed under Apache License 2.0. Earlier local metadata
+used `Apache-2.0 WITH LLVM-exception`; no LLVM source license exception is
+required for this repository unless future provenance review identifies copied
+LLVM-derived code or tables.
diff --git a/README.md b/README.md
index 449b6ea..c55e203 100644
--- a/README.md
+++ b/README.md
@@ -15,16 +15,45 @@ external libraries at runtime.
Object-file readers and broader ISA tables live in Jerboa `.ss` source modules.
+## Security and Release Gates
+
+```sh
+make verify
+make release-evidence
+```
+
+`make verify` runs the local security baseline, import check, normal tests,
+malformed parser regression tests, deterministic object-fuzz evidence, and
+native binary smoke tests. Release evidence is written to
+`dist/release-evidence/` with SBOM, reproducibility, and target proof status.
+
+Runtime file reads are bounded by `JASM_MAX_INPUT_BYTES` (default 64 MiB). Raw
+hex CLI input is bounded by `JASM_MAX_HEX_CHARS` (default 16 MiB).
+
+Generated native artifacts are ignored and must not be tracked. The root `jasm`
+binary is built by `make binary` and is a release artifact, not source.
+
+Production support also requires a reviewed `JASM_TARGET_PROOF_FILE` with the
+markers documented in `docs/release-evidence.md`. `JASM_REQUIRE_TARGET_PROOF=1`
+fails closed when that target proof is missing or incomplete.
+
## Run
```sh
-make test
+make verify
make binary
./jasm raw --arch x86-64 --syntax intel --hex '55 48 89 e5 c3'
./jasm raw --arch aarch64 --hex '20 00 80 d2 c0 03 5f d6'
./jasm raw --arch mips --hex '27 bd ff e0 03 e0 00 08'
```
+## Security Docs
+
+- `SECURITY.md`
+- `docs/threat-model.md`
+- `docs/parser-hardening.md`
+- `docs/release-evidence.md`
+
## Source API
```scheme
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..e79ce0a
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,57 @@
+# Security Policy
+
+`jerboa-asm` is a local parser/disassembler for raw bytes and object files. It
+has no intended network access, credential storage, daemon mode, shell execution,
+or FFI in repository source.
+
+Production claims require the release-plan gates and the repository production
+readiness tracker to be complete for this repository, including current
+SBOM/toolchain evidence and repeated clean-build reproducibility evidence.
+
+## Supported Status
+
+No public production-support commitment exists yet. Security-sensitive releases
+must be cut from a clean checkout after:
+
+- `make verify` passes.
+- `make target-evidence` records local blocked status or a reviewed
+ marker-complete target proof.
+- `make release-evidence` produces fresh evidence under `dist/release-evidence/`.
+- `git status --short` shows only intentional release changes and ignored
+ generated artifacts.
+- Generated binaries, object files, boot files, and WPO artifacts are not
+ tracked.
+- History has been reviewed for secrets or intentionally reset before first
+ public release.
+
+## Security Expectations
+
+- Treat raw byte strings and object files as hostile input.
+- Keep parser lengths, offsets, and counts inside their containing structures.
+- Keep `JASM_MAX_INPUT_BYTES` and `JASM_MAX_HEX_CHARS` bounded for production.
+- Do not add network, shell, or FFI behavior without updating
+ `.jerboa/security.json`, docs, tests, and release gates.
+- Keep target proof files free of object input samples, disassembly output
+ captures, private checkout paths, hostnames, and customer/user data.
+- Do not commit secrets, production `.env` files, operational hostnames,
+ customer/user data, generated binaries, or private infrastructure details.
+
+## Target Production Proof
+
+`JASM_TARGET_PROOF_FILE` may point at a reviewed proof file for a production
+target environment. `JASM_REQUIRE_TARGET_PROOF=1` fails closed when that proof is
+missing or marker-incomplete. The proof file must contain these exact markers:
+
+- `long_object_parser_corpus_status=reviewed`
+- `external_parser_review_status=reviewed`
+- `external_disassembler_parity_status=reviewed`
+- `cross_tool_corpus_status=reviewed`
+- `object_format_review_status=reviewed`
+- `resource_limit_review_status=reviewed`
+- `sensitive_artifact_policy=no-object-inputs-output-captures-private-paths-or-host-data`
+
+## Reporting
+
+Before public release, report issues privately to the repository owner. After
+public release, replace this section with a dedicated advisory contact, supported
+versions, and disclosure window.
diff --git a/docs/parser-hardening.md b/docs/parser-hardening.md
new file mode 100644
index 0000000..f463da2
--- /dev/null
+++ b/docs/parser-hardening.md
@@ -0,0 +1,56 @@
+# Parser Hardening
+
+`jasm` treats all bytes supplied through `--hex`, `--file`, or object-file
+commands as hostile.
+
+## Bounds
+
+- `JASM_MAX_INPUT_BYTES` limits file reads. The default is 64 MiB.
+- `JASM_MAX_HEX_CHARS` limits raw CLI hex input. The default is 16 MiB.
+- ELF section headers must meet the minimum entry size for the selected class.
+- Mach-O load commands must be at least 8 bytes, segment commands must be at
+ least 72 bytes, and declared sections must fit inside the load command.
+- Unix archive BSD long-name records must have numeric, non-negative name
+ lengths that fit within the member size.
+
+## Regression Coverage
+
+`tests/test-malformed-objects.ss` covers malformed hex, truncated ELF/COFF,
+zero-sized Mach-O commands, Mach-O segment section overruns, and invalid archive
+BSD long-name sizes.
+
+`make object-fuzz-evidence` adds deterministic malformed-object parser soak:
+
+- `object_fuzz_status: documented`
+- `object_fuzz_cases_minimum: 1024`
+- `object_fuzz_scope_status: raw-elf-macho-coff-archive-disasm`
+
+The harness generates 1024 stable cases across raw hex parsing, architecture
+disassembly, ELF, Mach-O, COFF, and Unix archive readers. Malformed inputs may
+raise structured conditions and are counted as rejections. Accepted objects must
+pass type predicates and section/member byte access invariants so delayed
+out-of-bounds metadata is caught before release.
+
+Before accepting new object readers or architecture decoders, add malformed
+cases for:
+
+- zero or non-advancing lengths;
+- count fields that exceed their containing structure;
+- offsets that point outside the bytevector;
+- size arithmetic that underflows or overflows logical container bounds;
+- large inputs that should trip the configured resource cap.
+
+## Target Review Gates
+
+`make target-evidence` records production-only blockers that cannot be satisfied
+by the local deterministic object-fuzz harness alone:
+
+- `long_object_parser_corpus_status`
+- `external_parser_review_status`
+- `external_disassembler_parity_status`
+- `cross_tool_corpus_status`
+- `object_format_review_status`
+- `resource_limit_review_status`
+
+Those markers default to `blocked-not-run` until a reviewed target proof file is
+attached through `JASM_TARGET_PROOF_FILE`.
diff --git a/docs/release-evidence.md b/docs/release-evidence.md
new file mode 100644
index 0000000..df298ce
--- /dev/null
+++ b/docs/release-evidence.md
@@ -0,0 +1,64 @@
+# Release Evidence
+
+Run:
+
+```sh
+make verify
+make target-evidence
+make release-evidence
+```
+
+`make release-evidence` writes `dist/release-evidence/` with:
+
+- git commit, status, and diff-stat;
+- selected non-secret build environment values;
+- security, unit, malformed-parser, object-fuzz, and binary smoke logs;
+- smoke-test output for x86-64 and AArch64;
+- SHA-256 hashes for the generated `jasm` binary and repository source files.
+- `sbom/`, a dependency/toolchain manifest with source and release-input hashes;
+- `reproducibility/report.txt`, comparing two clean local `jasm` builds after a
+ throwaway toolchain prewarm, plus the source manifest before/after the
+ measured comparison and repeated `object_fuzz_status`.
+- `target-evidence/`, a local blocked-status record or a reviewed target proof
+ copied with a SHA-256 sidecar.
+
+Generated files under `dist/`, `.build/`, the root `jasm` binary, native object
+files, boot files, and whole-program build artifacts are excluded from source
+hashes and must remain untracked.
+
+Release evidence must remain host-neutral. Use status fields such as
+`jerboa_home_status=present` instead of private toolchain paths, and `uname -srm`
+instead of full host-identifying platform banners.
+
+## Target Production Proof
+
+`scripts/target-evidence.sh` writes `dist/target-evidence/status.txt`.
+Without a proof file, local release evidence records:
+
+- `target_evidence_status: local-release-proof-recorded`
+- `target_asm_proof_status: not-run`
+- `long_object_parser_corpus_status: blocked-not-run`
+- `external_parser_review_status: blocked-not-run`
+- `external_disassembler_parity_status: blocked-not-run`
+- `cross_tool_corpus_status: blocked-not-run`
+- `object_format_review_status: blocked-not-run`
+- `resource_limit_review_status: blocked-not-run`
+- `production_asm_status: blocked-not-run`
+
+To attach reviewed target evidence, set `JASM_TARGET_PROOF_FILE` to a file that
+contains these exact markers:
+
+```text
+long_object_parser_corpus_status=reviewed
+external_parser_review_status=reviewed
+external_disassembler_parity_status=reviewed
+cross_tool_corpus_status=reviewed
+object_format_review_status=reviewed
+resource_limit_review_status=reviewed
+sensitive_artifact_policy=no-object-inputs-output-captures-private-paths-or-host-data
+```
+
+Set `JASM_REQUIRE_TARGET_PROOF=1` on production release hosts to fail closed
+when the proof file is missing or incomplete. Proof files must not contain
+object inputs, disassembly output captures, private paths, hostnames, or
+customer data.
diff --git a/docs/threat-model.md b/docs/threat-model.md
new file mode 100644
index 0000000..1af1846
--- /dev/null
+++ b/docs/threat-model.md
@@ -0,0 +1,38 @@
+# jasm Threat Model
+
+`jasm` is a local command-line binary/object-file parser and disassembler. It has
+no intended network behavior, credential handling, or daemon mode.
+
+## Assets
+
+- Local workstation integrity.
+- Files selected by the user for disassembly.
+- Release artifacts produced by `jerbuild`.
+- Developer trust in generated release evidence.
+
+## Trust Boundaries
+
+- Raw hex strings and input files are untrusted.
+- ELF, Mach-O, COFF, and Unix archive metadata is hostile input.
+- Test fixture writers are local tooling and may write only allowlisted `.jasm-*`
+ files.
+- `jerbuild` is part of the trusted build toolchain and emits ignored native
+ artifacts.
+
+## Security Goals
+
+- Do not execute shell commands from parsed input.
+- Do not perform network access.
+- Bound input sizes before disassembly and object parsing.
+- Reject malformed object structures before offsets or sizes are used for
+ slicing.
+- Keep generated binaries, object files, and boot artifacts out of source
+ control.
+- Produce release evidence from repeatable `make` targets.
+
+## Non-Goals
+
+- Perfect parity with `objdump`.
+- Sandboxing the whole process from inside this repository.
+- Parsing every object-file extension before the core format readers are
+ complete.
diff --git a/jasm b/jasm
deleted file mode 100755
index f8de3f9..0000000
Binary files a/jasm and /dev/null differ
diff --git a/lib/jasm/disasm.ss b/lib/jasm/disasm.ss
index 9a2b648..4256df4 100644
--- a/lib/jasm/disasm.ss
+++ b/lib/jasm/disasm.ss
@@ -4,6 +4,17 @@
(let ()
(define supported-architectures '(x86-64 aarch64 mips mipsel mips64 mips64el riscv32 riscv64))
+ (define default-max-hex-chars (* 16 1024 1024))
+
+ (define (configured-positive-int name default)
+ (let ([value (getenv name)])
+ (if value
+ (let ([n (string->number value)])
+ (if (and n (integer? n) (> n 0)) n default))
+ default)))
+
+ (define max-hex-chars (configured-positive-int "JASM_MAX_HEX_CHARS" default-max-hex-chars))
+
(define architecture-aliases
'((x86-64 . x86-64)
(x86_64 . x86-64)
@@ -80,6 +91,8 @@
(loop (+ i 1) (cons (string-ref s i) out))]))))
(define (hex-string->bytevector s)
+ (when (> (string-length s) max-hex-chars)
+ (error 'hex-string->bytevector "hex input exceeds JASM_MAX_HEX_CHARS" (string-length s) max-hex-chars))
(let* ([clean (clean-hex-string s)]
[n (string-length clean)])
(when (or (= n 0) (not (= (mod n 2) 0)))
diff --git a/lib/jasm/object/archive.ss b/lib/jasm/object/archive.ss
index 047a12b..f47769d 100644
--- a/lib/jasm/object/archive.ss
+++ b/lib/jasm/object/archive.ss
@@ -44,11 +44,29 @@
(bytevector-copy! bv offset out 0 size)
out))
+ (define default-max-object-bytes (* 64 1024 1024))
+
+ (define (configured-positive-int name default)
+ (let ([value (getenv name)])
+ (if value
+ (let ([n (string->number value)])
+ (if (and n (integer? n) (> n 0)) n default))
+ default)))
+
+ (define max-object-bytes (configured-positive-int "JASM_MAX_INPUT_BYTES" default-max-object-bytes))
+
+ (define (enforce-input-size who path bytes)
+ (when (> (bytevector-length bytes) max-object-bytes)
+ (error who "input exceeds JASM_MAX_INPUT_BYTES" path (bytevector-length bytes) max-object-bytes))
+ bytes)
+
(define (read-file-bytevector path)
(let ([port (open-file-input-port path)])
- (let ([bytes (get-bytevector-all port)])
- (close-port port)
- bytes)))
+ (dynamic-wind
+ (lambda () (void))
+ (lambda ()
+ (enforce-input-size 'read-archive-file path (get-bytevector-all port)))
+ (lambda () (close-port port)))))
(define (read-fixed-string bv offset size)
(require-range 'read-archive-bytevector bv offset size)
@@ -102,9 +120,11 @@
(let ([name (trim raw)])
(cond
[(string-prefix? "#1/" name)
- (let* ([name-size (string->number (substring name 3 (string-length name)))]
- [member-name (read-fixed-string bv data-offset name-size)])
- (list member-name (+ data-offset name-size) (- size name-size)))]
+ (let* ([name-size (string->number (substring name 3 (string-length name)))])
+ (unless (and name-size (integer? name-size) (>= name-size 0) (<= name-size size))
+ (error 'read-archive-bytevector "invalid archive BSD long-name size" name size))
+ (let ([member-name (read-fixed-string bv data-offset name-size)])
+ (list member-name (+ data-offset name-size) (- size name-size))))]
[else
(list (strip-trailing-slash name) data-offset size)])))
diff --git a/lib/jasm/object/coff.ss b/lib/jasm/object/coff.ss
index a935cc2..b849e48 100644
--- a/lib/jasm/object/coff.ss
+++ b/lib/jasm/object/coff.ss
@@ -61,11 +61,29 @@
(bytevector-copy! bv offset out 0 size)
out))
+ (define default-max-object-bytes (* 64 1024 1024))
+
+ (define (configured-positive-int name default)
+ (let ([value (getenv name)])
+ (if value
+ (let ([n (string->number value)])
+ (if (and n (integer? n) (> n 0)) n default))
+ default)))
+
+ (define max-object-bytes (configured-positive-int "JASM_MAX_INPUT_BYTES" default-max-object-bytes))
+
+ (define (enforce-input-size who path bytes)
+ (when (> (bytevector-length bytes) max-object-bytes)
+ (error who "input exceeds JASM_MAX_INPUT_BYTES" path (bytevector-length bytes) max-object-bytes))
+ bytes)
+
(define (read-file-bytevector path)
(let ([port (open-file-input-port path)])
- (let ([bytes (get-bytevector-all port)])
- (close-port port)
- bytes)))
+ (dynamic-wind
+ (lambda () (void))
+ (lambda ()
+ (enforce-input-size 'read-coff-file path (get-bytevector-all port)))
+ (lambda () (close-port port)))))
(define (read-fixed-string bv offset size)
(require-range 'read-coff-bytevector bv offset size)
@@ -101,13 +119,21 @@
(memv machine '(#x8664 #xaa64 #x0166 #x0266 #x0366 #x0466)))
(define (parse-section bv offset index)
- (make-coff-section
- index
- (read-fixed-string bv offset 8)
- (u32 bv (+ offset 36))
- (u32 bv (+ offset 12))
- (u32 bv (+ offset 20))
- (u32 bv (+ offset 16))))
+ (let ([section
+ (make-coff-section
+ index
+ (read-fixed-string bv offset 8)
+ (u32 bv (+ offset 36))
+ (u32 bv (+ offset 12))
+ (u32 bv (+ offset 20))
+ (u32 bv (+ offset 16)))])
+ (when (or (> (coff-section-size section) 0)
+ (not (zero? (coff-section-offset section))))
+ (require-range 'read-coff-bytevector
+ bv
+ (coff-section-offset section)
+ (coff-section-size section)))
+ section))
(define (parse-sections bv sections-offset count)
(let loop ([index 0] [sections '()])
diff --git a/lib/jasm/object/elf.ss b/lib/jasm/object/elf.ss
index 35ef188..0dce07c 100644
--- a/lib/jasm/object/elf.ss
+++ b/lib/jasm/object/elf.ss
@@ -130,11 +130,29 @@
(bytevector-copy! bv offset out 0 size)
out))
+ (define default-max-object-bytes (* 64 1024 1024))
+
+ (define (configured-positive-int name default)
+ (let ([value (getenv name)])
+ (if value
+ (let ([n (string->number value)])
+ (if (and n (integer? n) (> n 0)) n default))
+ default)))
+
+ (define max-object-bytes (configured-positive-int "JASM_MAX_INPUT_BYTES" default-max-object-bytes))
+
+ (define (enforce-input-size who path bytes)
+ (when (> (bytevector-length bytes) max-object-bytes)
+ (error who "input exceeds JASM_MAX_INPUT_BYTES" path (bytevector-length bytes) max-object-bytes))
+ bytes)
+
(define (read-file-bytevector path)
(let ([port (open-file-input-port path)])
- (let ([bytes (get-bytevector-all port)])
- (close-port port)
- bytes)))
+ (dynamic-wind
+ (lambda () (void))
+ (lambda ()
+ (enforce-input-size 'read-elf-file path (get-bytevector-all port)))
+ (lambda () (close-port port)))))
(define (elf-class-name n)
(case n
diff --git a/lib/jasm/object/macho.ss b/lib/jasm/object/macho.ss
index b160011..1efd778 100644
--- a/lib/jasm/object/macho.ss
+++ b/lib/jasm/object/macho.ss
@@ -103,11 +103,29 @@
(bytevector-copy! bv offset out 0 size)
out))
+ (define default-max-object-bytes (* 64 1024 1024))
+
+ (define (configured-positive-int name default)
+ (let ([value (getenv name)])
+ (if value
+ (let ([n (string->number value)])
+ (if (and n (integer? n) (> n 0)) n default))
+ default)))
+
+ (define max-object-bytes (configured-positive-int "JASM_MAX_INPUT_BYTES" default-max-object-bytes))
+
+ (define (enforce-input-size who path bytes)
+ (when (> (bytevector-length bytes) max-object-bytes)
+ (error who "input exceeds JASM_MAX_INPUT_BYTES" path (bytevector-length bytes) max-object-bytes))
+ bytes)
+
(define (read-file-bytevector path)
(let ([port (open-file-input-port path)])
- (let ([bytes (get-bytevector-all port)])
- (close-port port)
- bytes)))
+ (dynamic-wind
+ (lambda () (void))
+ (lambda ()
+ (enforce-input-size 'read-macho-file path (get-bytevector-all port)))
+ (lambda () (close-port port)))))
(define (read-fixed-string bv offset size)
(require-range 'read-macho-bytevector bv offset size)
@@ -134,9 +152,15 @@
(u64 bv (+ offset 40) endian)
(u32 bv (+ offset 52) endian)))
- (define (parse-segment-64 endian bv offset section-index)
+ (define (parse-segment-64 endian bv offset cmdsize section-index)
+ (when (< cmdsize 72)
+ (error 'read-macho-bytevector "Mach-O segment command is too small" cmdsize))
(let* ([nsects (u32 bv (+ offset 64) endian)]
- [section-base (+ offset 72)])
+ [section-base (+ offset 72)]
+ [section-bytes (* nsects 80)]
+ [required-size (+ 72 section-bytes)])
+ (when (> required-size cmdsize)
+ (error 'read-macho-bytevector "Mach-O segment sections exceed load command" nsects cmdsize))
(let loop ([i 0] [index section-index] [sections '()])
(if (= i nsects)
(cons index (reverse sections))
@@ -152,10 +176,12 @@
(vector (reverse sections) symtab)
(let* ([cmd (u32 bv offset endian)]
[cmdsize (u32 bv (+ offset 4) endian)])
+ (when (< cmdsize 8)
+ (error 'read-macho-bytevector "Mach-O load command size is too small" cmdsize))
(require-range 'read-macho-bytevector bv offset cmdsize)
(cond
[(= cmd #x19)
- (let* ([result (parse-segment-64 endian bv offset section-index)]
+ (let* ([result (parse-segment-64 endian bv offset cmdsize section-index)]
[next-index (car result)]
[new-sections (cdr result)])
(loop (+ i 1)
@@ -164,6 +190,8 @@
(append (reverse new-sections) sections)
symtab))]
[(= cmd #x2)
+ (when (< cmdsize 24)
+ (error 'read-macho-bytevector "Mach-O symtab command is too small" cmdsize))
(loop (+ i 1)
(+ offset cmdsize)
section-index
diff --git a/main.ss b/main.ss
index 9f43692..835e66f 100644
--- a/main.ss
+++ b/main.ss
@@ -25,16 +25,40 @@
(def (string->arch s)
(normalize-architecture s))
+(def (raise-jasm message . irritants)
+ (raise
+ (condition
+ (make-who-condition 'jasm)
+ (make-message-condition message))))
+
(def (parse-number s)
(let ([n (string->number s)])
- (unless n (error 'jasm "invalid number" s))
+ (unless n (raise-jasm "invalid number" s))
n))