Rust client for the MITRE eMASS (EaaS) REST API, regenerated from MITRE's eMASSRestOpenApi.yaml OpenAPI spec. This repo supplies the Rust leg of MITRE's client library that the upstream project does not ship natively — MITRE generates the client in Ruby, TypeScript, and Python, but not Rust.
Scope — generated vs hand-authored. The generated
client/crate (emass_client) is reproduced from MITRE's spec; its size is generated, not hand-written, and it is not hand-maintained between regenerations. The hand-authored portion of this repo is the thinemasserCLI wrapper insrc/and the parity/wire-body test harness intests/. SeeCodegen & regenerationfor how the client is produced.
The repo is a two-crate Rust workspace:
| Crate | What it is |
|---|---|
client/ |
emass_client (v3.22.0) — the generated eMASS REST API client. This crate is generated, not hand-maintained: it is reproduced from the spec through a patched openapi-generator 7.12.0 pipeline (see Codegen). |
emasser |
The hand-authored emasser binary + crate (src/, tests/) — the CLI front-end that drives emass_client. |
The regeneration tooling (patched generator + custom template + staged class dirs) lives in references/pipeline_inputs/.
| Step | Command |
|---|---|
| Clone & build | git clone <repo> emass_client_rust && cd emass_client_rust |
| Test (parity + wire-capture) | cargo test --workspace |
| Build the binary | cargo build → run ./target/debug/emasser |
End-to-end CLI wrapper (loads a local .env into the process environment, then runs the binary):
./run_emass.sh <subcommand> # e.g. ./run_emass.sh get test connectionemasser is a read-focused CLI: every operation is a get resource, with post / put / delete verbs available for the write paths. Authentication is mTLS client certificate + API key, provided entirely through environment variables — no secret is stored in the code.
configure writes a .env template to the repo root (existing keys are left untouched). Fill in your eMASS material:
./run_emass.sh configure # writes .env; ./target/debug/emasser configure also works.env keys. The mTLS cert + private key are a matched pair — if you set one, set the other too.
| Key | Required | Purpose |
|---|---|---|
EMASSER_HOST_URL |
yes | eMASS host, e.g. https://emas.example.gov |
EMASSER_API_KEY |
yes | API key / user-uid value |
EMASSER_CERT_FILE_PATH |
yes | mTLS client certificate (PEM) |
EMASSER_KEY_FILE_PATH |
yes | mTLS private key (PEM) |
EMASSER_KEY_FILE_PASSWORD |
no | passphrase for the encrypted private key |
EMASSER_USER_UID |
no | user-uid (falls back to 123 if unset) |
EMASSER_VERIFY_SSL |
no | false to accept self-signed servers |
EMASSER_PREFER |
no | mock header, e.g. code=200, dynamic=true |
EMASSER_CLI_DISPLAY_NULL |
no | false to strip null fields from output |
EMASSER_EPOCH_TO_DATETIME |
no | true to convert epoch timestamps |
EMASSER_DOWNLOAD_DIR |
no | where get artifacts export writes files |
run_emass.sh loads .env into the process environment automatically before invoking the binary, so you rarely set these by hand.
Always start here — it validates host + credentials before you run real queries:
./run_emass.sh get test connectionReads read as get <resource> [subcommand]:
# List systems (optionally filtered by CAMS id)
./run_emass.sh get systems all [--coams-id ID]
# Controls in a system
./run_emass.sh get controls forSystem --systemId 12345
# POA&M items in a system
./run_emass.sh get poams forSystem --systemId 12345
# One POA&M item
./run_emass.sh get poams byPoamId --systemId 12345 --poamId 6789
# Download a system's artifact bundle
./run_emass.sh get artifacts export --systemId 12345 --filename artifacts.tar.gzAll reads hang off get; post / put / delete are the write verbs, and configure sets up credentials. Invoke every read as emasser get <resource> [subcommand] [options]:
Systems
test connection— test the eMASS API connectionsystems all [--coams-id ID]— list systemssystems byId --systemId <id>— get a system by idsystem id [--systemName <name>] [--systemOwner <owner>]— find system(s) by name/ownersystem byId --systemId <id>— get a single system
Controls & assessments
roles all— list system rolescontrols forSystem --systemId <id>— controls in a systemcac controls --systemId <id>— CAC location of controlspac package --systemId <id>— PAC location of the system packageccmc assessments --sinceDate <date>— CMC assessment informationdashboards <name> --orgId <id>— a system dashboard
POA&M
poams forSystem --systemId <id>— POA&M items in a systempoams byPoamId --systemId <id> --poamId <id>— one POA&M itemmilestones byPoamId --systemId <id> --poamId <id>— milestones for a POA&Mmilestones byMilestoneId --poamId <id> --milestoneId <id>— one milestone
Results, assets & artifacts
testResults forSystem --systemId <id>— test results in a systemhardware assets --systemId <id>— hardware assetssoftware assets --systemId <id>— software assetsartifacts forSystem --systemId <id>— artifacts for a systemartifacts export --systemId <id> --filename <f>— download an artifact (-Ccompress,-oprint to stdout)
Workflows
workflow_definitions forSite— all workflow definitionsworkflow_instances all— all workflow instancesworkflow_instances byInstanceId --workflowInstanceId <id>— one workflow instance
| Path | Description |
|---|---|
client/ |
Vendored emass_client crate (generated: src/, Cargo.toml, README.md). |
src/ |
Hand-authored top-level crate: the emasser CLI, wire-format converters, and emass parity tests. |
tests/ |
Hand-authored integration tests: byte-parity and full wire-body capture. |
spec/ |
The eMASS OpenAPI spec (eMASSRestOpenApi.yaml) that drives codegen. |
references/pipeline_inputs/ |
The codegen recovery kit — patched generator, custom template, and staged class dirs. See Codegen. |
The committed client/ crate is the output of a custom openapi-generator 7.12.0 Rust pipeline (patched RustClientCodegen generator + custom mustache templates) — not stock template output. To keep it bit-exact after any spec or template change, run the drift guard:
source ~/.local/toolchain/env.sh # sets JAVA_HOME + OGCJAR
./regen.sh verifyregen.sh verify regenerates client/ into a temp dir and fails if any file diverges from the committed crate — this is the guard that proves regeneration is zero-divergence (parity). To instead see how the spec differs from stock generator output, ./regen_client.sh summary prints the divergent set (the custom-template additions).
Regeneration notes:
REGEN_NOTES.md.
ci.yml— builds and lints (clippy -D warningsover the whole workspace;rustfmton the hand-authored crate only) and runs the parity + wire-body test suite onstableandbeta. The generatedclient/is exempt from lint/fmt by construction.codegen.yml— on spec change, nightly, and on dispatch, regenerates with the pinned toolchain and asserts 196/196 parity, failing the build on drift.
MITRE's client library (mitre/emass_client) is generated for Ruby (gem emass_client — the dependency of the mitre/emasser CLI), TypeScript (@mitre/emass_client, used by the SAF CLI), and Python — Rust is not among them. mitre/emasser is MITRE's official Ruby CLI: a thin business-logic wrapper around the REST API, not the API layer itself.
This repo reproduces the missing Rust leg from the same upstream eMASSRestOpenApi.yaml through the patched pipeline — role-for-role, the Rust equivalent of the Ruby gem. It keeps the upstream contract intact: crate emass_client (v3.22.0) and the emasser binary name.
Two different licenses apply here — the generated client and the hand-authored wrapper are separate:
client/crate (emass_client) — Apache-2.0, as declared inclient/Cargo.toml. This is the generated client reproduced from MITRE's upstream spec, so its license is carried from upstream, not set by this repo.emasserwrapper andtests/(the hand-authored layer) — MIT, per the rootLICENSE.
- MITRE eMASS (EaaS) REST API — the spec this client is generated from.
- MITRE emasser — reference Ruby CLI.
- openapi-generator — the generator behind the custom pipeline.