mirror of
https://github.com/morluto/rea.git
synced 2026-11-12 09:52:27 +00:00
7aca4cef64
* feat(audit): report what a shipped app exposes to static analysis
Adds `audit_release_exposure` and `rea audit-release-exposure` to report
source maps, Electron fuse implications, extractable payloads, debug
information, build metadata, and credential markers. Checks carry stable
IDs, observations, statuses, and fixed remediation, while incomplete and
unassessed checks remain visible without implying a security verdict.
Credential findings include only rule IDs and locations. The CLI
supports `--fail_on` severity thresholds and exits 3 when an exposed
check meets the threshold.
* fix(audit): keep incomplete coverage unknown across text, fuses, Go flags and cancellation
Probe files with unrecognized names as text, keep undecided fuse slices
unknown, forward opaque container coverage, read paths from Go build flags,
and compare inventoried digests before accepting owner facts.
Keep typed cleanup failures and attach the partial report when a later owner
is cancelled. Pin the verifier's @electron/fuses version and move the tests
to the named contract family.
* fix(audit): match package members by source spelling and close remaining coverage gaps
Reopen package members by their source spelling and keep caller path
traversal in directory reads. Parse quoted and attached Go build flags, bind a
native image fuse read to its own digest, and keep reader resources and the
audit's partial report when cleanup or cancellation combine failures.
* fix(release-exposure): bind package members by ordinal and follow named map references
Package members were matched to container entries by sourcePath, which is
not unique in a PyInstaller executable, through a queue that only moved when
a member was reopened. Bind by container-relative path and duplicate ordinal,
the numbering inventory uses, so read order cannot change which bytes a
member gets.
A sourceMappingURL naming a file without a map extension was ignored. Local
targets are now examined as maps whatever their name, and a target already
scanned as plain text leaves coverage unknown.
* fix(release-exposure): match data: source map scheme case-insensitively
URL schemes are case-insensitive, so an inline declaration such as
//# sourceMappingURL=DATA:application/json;base64,... was routed to the
local-reference path, which ignores scheme URLs. Its embedded sources were
silently dropped and source_map_sources reported not_observed.
* fix(release-exposure): normalize declared map targets and count unreached ones
A sourceMappingURL that decodes to a decomposed name (cafe%CC%81.json)
never matched the inventoried member, whose logical path is NFC, so the
map was scanned as ordinary text and its sourcesContent went uncounted.
Map-target lookups now use an NFC key on both the record and lookup
side; the declared URL is left as written.
A declared map target that is never reached is now counted as a skipped
map, so the source-map checks read as unknown coverage instead of
not_observed.
* fix(release-exposure): recover indexed leaves after any map format failure
An indexed map whose one leaf has malformed mappings (such as AA) threw a
format failure that only recovered leaves for unsupported sections, so a
valid sibling leaf with sourcesContent was dropped and
javascript.source_map_sources read unknown instead of exposed. Leaves are
now recovered for any format failure, with the envelope parse guarded so
invalid JSON still falls through to the unparsed count.
A nested package that inventory recognized but did not expand was probed
as a plain binary and left the source-map checks at not_observed. It now
marks coverage unknown and records a limitation.
Reader tests assert the javascript.source_map_sources status for the NFC
map-name cases as well.
* fix(release-exposure): count an unexpanded nested package as a readable member
An unencrypted nested package that inventory recognized but did not
expand is still a member its parent package already read. Count it as
readable so packaging.extractable_payload reports exposed, while its
own contents keep coverage unknown.
* fix(release-exposure): bound the indexed leaf fallback by decoder limits
The fallback walk after a map format failure expanded every section and
built a full ancestor path per leaf, so a map refused for nesting depth
could still allocate far past the decoder budgets. Walk only to the
64-level section depth and the shared record budget, keeping leaf maps
without materializing section paths.
* fix(release-exposure): collect UNC roots from Go flag paths
A flag such as -I\\buildhost\sdk\include matched none of the path roots
in GO_FLAG_PATH, so a network path that was the only one in complete
build info left go.build_paths at not_observed. Accept \\host\share
roots alongside the slash-rooted, dot-relative and drive-letter forms.
* fix(release-exposure): keep Electron undecided without positive proof
The desktop owner names Electron only from an ASAR layout, so an asar: false
build has no candidate. A complete scan with no candidate was reported as
not_electron, which outranks unresolved and safe fuse outcomes and hid them
as not_applicable.
Leave the family unknown unless the fuse holder rules Electron out: an app
bundle with no Electron Framework, or a directory with complete coverage
whose native images were all read and hold no sentinel. A directory with no
native image is not proof, so its fuse checks now report unknown.
* fix(release-exposure): decode wide text members before scanning
A member's kind bypassed the NUL guard, so a UTF-16 plist was decoded as
UTF-8, matched nothing and still counted as scanned. A directory holding
only that member reported text.credential_markers as not_observed.
Decode by byte order mark at one boundary instead. UTF-16 is scanned in
either byte order, and inline maps read the same text. UTF-32 and NULs no
mark explains count as skipped, whatever the member's kind. A binary
plist keeps its raw scan. Unnamed members with a mark now reach the
scanner, and the plist decoder shares the same mark detection.
* fix(release-exposure): follow file: URL source map declarations
The scheme guard in noteLocalMapReference returned on every URL scheme, so
a declaration such as file:///release/debug.json was dropped with the remote
ones. A member without a .map name was then scanned as ordinary text and
javascript.source_map_sources reported not_observed.
Convert file: URLs with fileURLToPath and record them in mapTargets through
the same step as relative declarations. A target that is never reached, or
that was already scanned as text, counts as skipped, and so does a malformed
file: URL. A file: URL names one absolute location, so a .map target outside
the inventory stays unassessed rather than being trusted by its name. Remote
schemes stay ignored.
* fix(release-exposure): match backslash-relative Go flag paths
GO_FLAG_PATH accepted dot-relative roots only with a forward slash, so
`-I..\sdk\include` and `-I.\sdk` produced no path and go.build_paths came
back not_observed. Accept either separator after the dots.
The CLI acceptance test now expects unknown for electron.run_as_node on a
directory with no native images, matching the service.
* fix(release-exposure): keep fuses unknown on incomplete inventory
A directory inventory that stops at an acquisition limit never reports
the images it did not reach, so the native image sample has no omission
and safe fuses on an included helper settled to not_observed even though
scan coverage was unknown.
Treat unknown coverage like a truncated sample until the Electron
executable is accounted for. A selected native file is that executable,
so it keeps its decided fuse result.
* fix(release-exposure): decode binary plists before scanning
A binary plist stores each string as ASCII or UTF-16BE. Scanning the raw
bytes as UTF-8 missed any string the encoder kept in UTF-16, such as one
with a non-ASCII character, and still counted the member as fully
scanned, so text.credential_markers read not_observed.
Decode through the plist owner and scan its strings, dictionary keys and
data. A plist that cannot be decoded keeps its raw bytes in the scan and
counts as skipped, so coverage stays unknown.
* fix(release-exposure): keep UTF-8 members that hold a NUL
Any NUL in a member's first 512 bytes made the decoder give up, so a script
with a literal NUL in a string never reached the credential or inline-map
checks. An exposed marker in it read as unknown, and --fail_on high exited 0.
Validity alone cannot tell wide text from UTF-8, since ASCII in UTF-16 is
valid UTF-8. Treat a header that is an eighth or more NUL bytes as wide text
and anything not UTF-8 as undecoded, and scan the rest.
The docs now separate BOM-marked UTF-16, which is scanned, from wide text
with no byte order mark, which is not.
* fix(audit): scan every string a binary plist stores
The plist scan read only the decoded value, which drops objects the root no
longer references and entries a later duplicate key replaced. Those bytes
still ship, but the audit marked the scan complete, so a credential stored
there read as not observed and --fail_on high exited 0.
Read strings, keys and data from the object table instead. A stored object
that cannot be read leaves the member unassessed, and a total byte budget
bounds table entries that overlap to repeat the same text.
* fix(audit): keep packaged native images from ruling out Electron
The applicability check only looked at the "native images" omission. An
Electron executable inside a compressed .NET or PyInstaller member is recorded
under "packaged native images", so a directory whose on-disk hosts had no fuse
sentinel read as not Electron and all four fuse checks as not applicable.
Treat that omission as an unread image too.
* fix(audit): keep readable plist text when one object is unreadable
Throwing on one unreadable stored object discarded every string already
decoded, so a UTF-16BE credential beside a truncated unused object was lost:
the raw bytes that replaced it cannot match NUL-separated text.
Return the decoded text with complete false instead, and keep the raw bytes
in the scan beside it so ASCII in the unread object is still seen. The member
stays unassessed. Text past the budget ends the same way.
* fix(audit): read escaped inline maps and extensionless SEA entries
A data URL may percent-escape its base64 payload, so a map such as one padded
with %3D did not decode and the audit counted no embedded source map. Decode
the escapes before reading the base64.
A directory walk classed a SEA entry by its code path, so a main script whose
code path names no script was never scanned as JavaScript and its inline map
went unseen. Class it by the role the SEA metadata gives it.
* fix(audit): check plist text against the budget before decoding it
decodeBinaryPlistText decoded each stored object before comparing its size
with the remaining budget, and it keeps going after an object is rejected so
later text is still read. A plist under the input limit could repeat a large
range through overlapping table entries and force gigabytes of decoding that
the audit then discarded.
Separate finding a stored payload from decoding it, so a range past the
remaining budget is rejected without allocating its text. Earlier text and
the incomplete result stay as they were.
* fix(audit): count a packaged PE with an unread header as a native image
A package member whose PE signature lies beyond the 4 KiB probe recorded only
a PDB failure. The image was neither read nor listed under packaged native
images, so a directory whose on-disk hosts had no fuse sentinel read as not
Electron and all four fuse checks as not applicable.
Count it as a packaged native image, the omission that keeps the question
open, and keep probing it for text as before.
* fix(audit): keep cleanup-incomplete errors from composed readers
A desktop, fuse, Go or Rust failure became a string on that check, so an
error with unfinished cleanup lost its resources and live bindings while the
audit reported success, and the MCP handler does not close the service after
each request.
Treat unfinished cleanup like cancellation: stop the remaining owners and
return the error with the partial audit. When the owner attached its own
partial, keep the error and replace the partial, so cleanup stays attributed.
* fix(audit): keep safe fuses unknown past a packaged native image
The fuse check counted sampled-out images as possibly unread but not native
images inside a package. A complete directory scan with a safe-fuse image on
disk, no ASAR hint, and an unopened packaged image reported the four Electron
checks as not_observed, although the Electron executable could be that image.
The fuse check, the Go and Rust checks, and the Electron rule-out each decided
this for themselves and had drifted apart. Move the decision to one domain
predicate, nativeImagesMayBeUnread, and use it in all three. A hinted
executable that was read still settles the check.
* fix(audit): settle fuses only on an identified host, and read Bun and HTML maps
A retained helper set electron_executable_included because the rank marks
every .exe or extensionless sibling of resources/app.asar. With more than four
siblings, or an inventory that stopped early, safe fuses on a helper reported
not_observed while the host went unread. Rank stays a sampling hint. The check
now settles only on an executable named as the host, or when inventory was
complete and every executable that could be the host was sampled.
A Bun sourcemap region is named .bunmap, so its role was lost and a complete
audit reported no source maps. Carry the region role from the reader's metadata
into the member view, in the expanded and unexpanded paths, and treat it as a
JavaScript map so an unparsable region stays unresolved, not a debug companion.
An HTML member was scanned as text but its inline scripts were never checked
for source maps. The HTML owner now returns each body, the reader examines it
like a script file, and bodies past the owner's limit count as skipped.
* fix(audit): charge map reads to the count before opening the member
An oversized or unreadable .map returned before readSourceMap counted it, so
the allowance of 32 never ran out. An unexpanded .NET or PyInstaller package
could then decompress every listed map member, about 1 MiB each, up to the
4,096 entry cap.
The count bounds reads, so examineMap now reserves the slot before it opens the
member. A map past the count is skipped unopened, and a linker map past it is
still settled from its bounded prefix. An inline data: map is already in memory
and keeps its charge at the point it is parsed.
* fix(audit): examine scripts HTML loads whatever they are called
isJavaScriptMember knows a script by its suffix or an assigned kind, and the
reader dropped the script references the HTML owner parses. An extensionless
main loaded by <script src="main"> was scanned as ordinary text, so a complete
inventory reported javascript.source_map_sources not_observed with shipped
sources in its inline map.
The reader now resolves each JavaScript script reference against the page and
its base href, and a local target without a JavaScript name is examined as a
script when reached. A target read before its HTML file, never reached, or not
placeable on disk counts as a skipped map, so the check stays unknown.
* fix(audit): charge sibling map reads to the map count
Every generic .map beside a selected file got a full 1 MiB read and a
parse, with no cumulative bound, so the 4,096-entry listing allowed about
4 GiB of reading for one small selection.
Move the slot rule into chargeMapRead, which examineMap and sibling
classification now share. Past the count a sibling reads only the header:
a linker map is still identified, and one that may be a source map stays
a skipped companion.
* fix(audit): report cleanup failures raised by member reads
A close failure during an embedded-package probe, member read or inventory
reaches the shared read filter as an ordinary reader failure. The filter kept
only cancellation and integrity, so the member became a skipped read, inspect
succeeded, and the retained descriptor was reported nowhere. MCP does not close
the service after each request, so no caller saw it.
Propagate any failure that carries cleanup, whatever its reason, so it reaches
releaseExposureFailure and the audit reports its retained resources.
* fix(audit): charge unsuccessful text reads to the byte allowance
An oversized, undecodable, or failed text read left textBytes unchanged, so
every member got the full per-member budget and the cumulative allowance did
not bound what a package decompressed. Count the bytes member reads produce
and charge them whatever the read yields. An oversized file on disk still
costs only its probe.
* fix(audit): bound the paths kept for HTML script targets
A base href is copied into every script target it resolves, so a page under
the text member allowance could retain hundreds of megabytes of paths. Charge
each new target's resolved path to a byte allowance and leave targets past it
unassessed.
* fix(audit): keep examining a page loaded as a script as HTML
A script element naming an .html member promoted that member to a
script, and the text pass then chose one reading. The page's own script
elements were never read, so an inline map in it was lost and a shipped
sourcesContent went unreported.
Run the script reading and the HTML reading independently, and list the
script target allowance among the cases that leave source map coverage
undecided.
* fix(audit): detect credential markers that end in a hyphen
The Google, GitLab, and Slack rules allow a hyphen in the token but ended
on a word boundary, so a token ending in a hyphen at the rule's minimum
length was missed and the audit reported the check as not observed.
Open-ended rules now take the whole token, and the fixed-length Google
rule checks the full token alphabet after its last character.
* fix(audit): confirm FAT identity for probed package members
The package probe treated a decoded FAT table as a universal Mach-O. A
JVM class past the 4 KiB probe shares the FAT magic, so its truncated
prefix decoded as a table, the member counted as an unread native image,
and Electron could not be ruled out of a complete scan.
Pass the member's declared size to the sniff and take identity from
classifyFatContainerEvidence. A member with no usable size, or with
slices past the probe, stays counted as possibly native.
* fix(audit): admit binary plists in package member probes
A package member's probe judged text by its own NUL test, which accepted
byte order marks but not the binary plist signature decodeMemberText also
reads. A PyInstaller executable shipping a binary Localizable.strings was
rejected without a scan or a skipped count, so a UTF-16BE private key
marker inside it could report not_observed.
Name the encodings that explain their own NULs in one predicate, and move
the plist fixture builders to module scope.
* fix(audit): locate Go findings only in images that retain build paths
The exposed decision required non-empty paths, but the locations took
every image whose build info read. An image with no paths was named as a
source of the leak beside the one that had them.
One predicate now decides both.
* fix(audit): keep completed findings when member cleanup fails
A descriptor close failure aborts the member scan, and the scan's state
was dropped with it, so the caller got a typed cleanup failure and no
report. Source maps already counted and credential hits already collected
were lost.
The reader now hands the service what it assembled, with coverage unknown
and a limitation saying so, alongside the failure. The service runs that
scan through its existing stopped-audit path: no later owner runs, and the
report goes on the error as its partial observation.
* fix(audit): keep coverage unknown for nested ASARs in package hosts
A member of a PyInstaller or .NET host reaches the binary probe as a
plain file. An ASAR among them has a NUL-bearing header, so the probe
dropped it with no traversal and no omission, and source map checks could
read not_observed with complete coverage.
Ask the ASAR owner's signature probe, and record a match as a nested
package that was not expanded, as inventory-classified ones already are.
* fix(audit): let native format facts outrank member names
examineMember tried the name-based text and map routes first, so a PE an
owner identified inside an ASAR, named payload.json, was read as text.
Its CodeView path and the packaged-native omission were both lost, and
native.pdb_path read not_applicable.
Route an owner-established native format to the native probe first, and
count an encrypted one as a packaged native image for the same reason.
* fix(audit): report relative paths given to compiler path flags
go.build_paths only kept rooted paths, so retained build settings like
CGO_CFLAGS=-Iprivate-sdk read not_observed even though the setting names
a directory.
Take the relative argument of a C compiler path flag, attached or in the
next field. Scope this to compiler settings, because Go's own tools use
the same letters for non-paths such as -B gobuildid and -T 0x1000.
* test(javascript): expect retained text on SVG inline scripts
The SVG test from main predates this branch's inlineScripts text field,
so each side passed alone and only their merge failed.
* fix(audit): keep an unresolved Electron host's fuses unknown
fuseCheck decided from whatever outcomes the images reported, so a host
with no fuse answer read not_observed as soon as any other image in the
directory reported safe fuses.
Pass the images named as the host into the report and leave a check
unknown when one of them has no answer for it. Other images stay free to
have no fuses, because helpers in a real Electron install have none.
* fix(audit): bound the paths kept for local source map targets
noteMapTarget kept every declared target resolved against its member's
directory, so a short URL under a long directory could retain far more
than the script's own size, with no cumulative limit.
Add the allowance noteScriptTarget already has. A target past it stays
unassessed and counts as a skipped map, and is never read.
* fix(audit): borrow the audit's scope admission for inventory
inspect holds resources.run for the whole audit, and inventoryArtifact
entered the same scope again. With failed cleanup pending from another
audit, the inner run waits for a drain that waits for the outer run.
Add inventoryArtifactInScope, which takes the caller's admission.
* fix(audit): run the exposure verifier's commands under supervision
The verifier launched npm and the CLI with raw execFile and then removed
its temporary tree, so a timed-out child could outlive the tree it was
using.
Use the shared verifier commands and close them before removing the tree.
Their exit error carries stdout on its snapshot, so the audit's exit-code
branch reads it from there.
* fix(audit): read relative -L paths and split flag arguments
The relative-path reader handled C compiler settings only, so a directory
kept through Go's own linker flag, such as -ldflags='-L private-sdk -s -w',
reported go.build_paths as not_observed.
A quoted flag and argument also reached it as one field. The separating
space stayed on the argument, which reported rooted paths twice and kept a
leading space on relative ones.
Give -ldflags its own pattern that matches only -L, so -B gobuildid and
-T 0x1000 stay ignored, and consume the separator in the flag patterns.
* fix(audit): keep embedded leaves beside schema-invalid map fields
The reader recovers independent indexed leaves only after a
SourceMapFormatFailure, but inspectSourceMap let the schema's ZodError
through. A sibling with mappings "!", a section with a bad offset or a
root with a bad field skipped recovery, so a valid leaf with
sourcesContent reported javascript.source_map_sources as unknown.
Normalize schema rejection in SourceMapFormat, which owns these parses,
so every structural failure reaches consumers as a format failure. The
message is unchanged, and the codec and web fetcher already map both
cases to the same result.
* fix(audit): keep packaged executables' own packages unknown
examinePackagedBinary counted a native image inside a package and moved
on, while only on-disk images reached the embedded-package probes. An
ASAR carrying a PyInstaller, Bun, Node SEA or .NET executable with a
source map therefore scanned complete and reported
javascript.source_map_sources as not_observed.
Run the same classifier on packaged images. The probes read carrier
offsets from a file, so the member's bytes stay in a temporary file for
the probe alone. A detected package keeps member coverage unknown, as a
nested ASAR does, and an image past one file's total byte allowance
stays unprobed and unknown. A plain native member leaves coverage intact.
* fix(audit): read an app's sampled images for fuses
A .app target sent only the bundle candidate to the fuse reader, which
resolves to the outer Electron Framework. A sidecar with RunAsNode enabled
was never read, so the check reported not_observed in the app view while
the directory view reported exposed.
Send the bundle candidate first and then the sampled native images. An
image whose digest matches the bundle's read is skipped, so the framework
is not read twice. A sidecar's safe fuses cannot settle the outer framework,
so a bundle read with no answer for a fuse keeps that check unknown.
* fix(audit): read a Node shebang as script identity
The path classifier gives an extensionless executable a resource kind,
so a script such as bin/runner with a `#!/usr/bin/env node` header was
scanned as text without its inline maps being examined or counted. A
complete inventory then reported no shipped sources for it.
The probe holds the first bytes a member reader sees, so establish the
identity there. The script keeps the usual outcomes: a map that is read
counts, and one past an allowance or undecodable stays unknown.
* fix(audit): keep linker strings out of Go build paths
Reading `-X 'main.usage=-L level'` as a library directory made
go.build_paths report `level`, so a plain string could fail an audit
under --fail_on low.
Read the optional package selector once, before the setting's first
flag, and keep the argument of -X attached to it, so a string it sets
is never scanned as another option.
* fix(audit): keep a failed probe directory removal owned
A packaged image's probe copies the member's full bytes into a temporary
directory. When removing it failed, the error became an ordinary
unreadable probe: the audit could still succeed, nothing could retry the
removal, and the client heard nothing about the leftover bytes.
Hold the directory in the reader's resource scope, so close retries it,
and report the unfinished cleanup without replacing a primary failure.
* fix(audit): keep a declared .map from reading as a linker map
A script's sourceMappingURL=assets.map was dropped because the name
already looked like a map. A malformed assets.map then settled as a
linker map, so both source-map checks read not_observed and
native.debug_companions reported an exposure the release does not ship.
Keep a generic .map name as a declared target and read it as a
JavaScript map, in either scan order, so it stays unresolved.
* test(audit): rethrow typed errors from release exposure checks
A failed Result was rewrapped in a plain Error, which dropped its type,
cause and cleanup details from the test output.
* fix(audit): match companions by member identity, not spelling
An ASAR member's location is relative, and a declared map target is
absolute, so a malformed assets.map read before z.js stayed a linker
companion. The examined-map lookup, which is normalized, then returned
early, leaving both source-map checks not_observed.
Index companions by memberLocationKey and keep each reported spelling
under it. Spellings stay distinct because symlinks can make them differ.
* fix(audit): retract only guessed linker maps on a declaration
A script declaring sourceMappingURL=symbols.pdb after the scan reached
symbols.pdb removed the shipped PDB from the companion list, because a
late declaration retracted any companion. native.debug_companions could
then read not_observed.
Keep name-identified companions in their own set, and retract only maps
that were read as non-JSON and guessed to be linker maps.
* fix(audit): record an unfollowed map link as skipped
The directory and ASAR readers do not follow links, so a symlinked
app.js.map dropped out before any map counter moved. Its target was
scanned as plain text, and both source-map checks read not_observed.
Count a link that names a map as skipped wherever entries reach the
audit, and mark it examined so a declaration does not count it twice.
* fix(audit): read relative paths in Go compiler and assembler flags
A binary built with -gcflags=-I private-sdk keeps that setting, but
relative parsing covered only C compiler settings and -ldflags, so the
directory dropped out of go.build_paths.
Give -gcflags and -asmflags their own path options, taken from what
go tool compile and go tool asm document, and strip the package selector
as -ldflags does. The assembler's -D defines a symbol, so it is not one.
* docs(audit): state the packaged image read allowance
Packaged ELF, Mach-O and PE images are read in full and copied to a
temporary file, sharing one max_file_bytes allowance, but the docs and
coverage.allowances still said only a PE gets more than a header read.
Name the allowance and the copies in docs/release-exposure.md,
RELEASE_EXPOSURE_ALLOWANCES and the max_file_bytes description.
* docs(audit): say how go.build_paths treats rooted -X values
A rooted -X value cannot be told from a file path, so the audit reports
it. State that, and why, so the rule is a contract rather than a side
effect of how flags are scanned.
* fix(audit): keep a declared sibling map out of the linker guess
When the selected file declared a sibling map, the sibling classifier
never consulted the declaration. A malformed assets.map then read as a
linker map and raised native.debug_companions.
Leave a declared sibling to the unreached-target accounting, as members
already are, so it stays an unresolved source map.
* fix(audit): keep undecodable Go and Rust metadata unknown
Unsupported meant two things: a container this reader does not handle,
and metadata the image holds in a form the reader cannot decode, such as
a compressed .dep-v0 section. Both read as not_applicable, so an image
that carries metadata reported that the check did not apply.
Mark the second case on the format failure and carry it on
AnalysisUnsupportedTargetError, so the audit records a failed read and
stays unknown. The tools' own errors and messages do not change.
* fix(audit): keep coverage unknown for a PE header past the probe
A packaged member whose PE signature lies beyond the probe prefix stayed
unclassified, so the embedded-package probe never ran and coverage stayed
complete. A map inside such an image then read as not_observed.
Record the member as an unexamined package where it is already marked as
a possible native image.
* fix(audit): read the scripts of a standalone SVG
An SVG can carry a script with an inline source map, but only .html and
.htm members reached the script owner, so such a file left every map
counter at zero and javascript.source_map_sources read not_observed.
Treat .svg as a script-bearing page. htmlArtifactReferences already
reads SVG script elements, so this adds no parsing.
* fix(audit): keep every possible host when no name picks one out
With no named Electron host, every sibling ranks alike and
electron_host_paths stayed empty, so one image's safe fuses settled the
checks even when another possible host reported none.
Keep all sampled candidates as hosts in that case, so a candidate
without fuses leaves the checks unknown.
* fix(audit): read a text-named native member by its bytes
A PE member called payload.json took the text route, so it reached no
native probe, and its CodeView path and packaged-native uncertainty were
lost.
Decide from the bytes the text read already loaded, so real text costs
no extra read and the map and text allowances stay as they were.
* fix(audit): let a map or script read identify a native member
A package lists names without formats, so a PE called payload.js.map
took the map route and never reached a native probe. Its CodeView path
was lost, and with nothing counted as failed, native.pdb_path could read
not_applicable. A PE at a declared script or map target was lost the same
way, because declaration overrode the route.
Decide from the bytes the route already read, in the map route as in the
text route, and keep the listed kind for a promoted script target. Real
text and maps cost no extra read, so those allowances are unchanged.
* fix(audit): name a symlinked sibling debug companion
Selecting an executable skipped every symlink beside it before the name
check, so an app.pdb link left no companion path and no skip count, and
native.debug_companions read not_observed. Selecting the directory
reports the same link.
Check the name first. The map branch already needs a regular file, so no
link is followed.
* fix(audit): keep map coverage unknown for a linked script
A link named app.js to an extensionless payload was skipped as a link,
and its target was read as plain text with no map directives parsed. An
inline map there left no parsed or skipped count, so
javascript.source_map_sources read not_observed. Only links with a map
name were counted.
Count a link under any name that can declare a map, the set an unread
member already uses. It stays one omission when a page or a directive
also names it. The target is still not followed.
* fix(audit): keep a declared JavaScript map beside a selected file unknown
A local sourceMappingURL with a JavaScript map name such as app.js.map
was dropped on the assumption that it would be examined as a member.
When the selection is a file, sibling .js.map files are never read, so
the declared map left javascript.source_map_sources not_observed while
the same target spelled as a file: URL left it unknown. Record every
local target so an unreached one counts as skipped.
* fix(audit): read paths a C compiler forwards to the linker
CGO flags can hand linker options through -Wl,a,b or -Xlinker a. The
compiler flag parser saw -Wl,-L,private-sdk as one field and missed the
relative library directory, so go.build_paths reported not_observed.
Split forwarded options out before reading paths and read them with the
linker's own path options (-L, -T, --library-path, --script). This also
stops -Xlinker -Bsymbolic from being read as the compiler's -B prefix.
* fix(audit): read forwarded linker options by their linker meaning
The forwarded linker flag pattern read -Ttext=0x400000 as a script path
named text=0x400000, and it ignored -I, so -Xlinker -Ilib/ld-custom.so
lost the interpreter path the compiler flag pattern found before the
split.
Exclude the -T section and segment address options (bss, data, text,
text-segment, rodata-segment, ldata-segment) and read -I and
--dynamic-linker as paths.
* fix(audit): split Go flags as Go does and read external linker flags
Go splits a flag value with quoted.Split: a field that starts with a
quote runs to the matching quote, and any other quote is a literal
character. The reader stripped every quote, so CGO_CFLAGS
-I"/home/O'Neil/include" reported /home/ONeil/include, while cc was
given the directory "/home/O'Neil/include", quotes included.
-ldflags kept -extldflags values with the Go linker flags, where only
-L counts, so -extldflags=-Lprivate-sdk reported no path. The values
are now read as the C compiler driver reads them, including -Wl, and
-Xlinker forwarding.
A package member named payload.json or payload.js.map that holds an
ASAR took the text or map route, which checked only native signatures,
so the nested archive was scanned as text and coverage read complete.
The route's own read now recognizes the ASAR signature as well, and the
nested package leaves coverage unknown.
* fix(audit): keep a named script beside a selected HTML file unknown
A script element whose target had a JavaScript name such as app.js was
dropped on the assumption that it would be examined as a member. When
the selection is an HTML file, sibling scripts are never read, so a
sibling holding an inline map left javascript.source_map_sources
not_observed while the same target named app left it unknown. Record
every local script target so an unreached one counts as skipped.
* fix(audit): read a retained -pgo setting as one profile path
`-pgo file` names a single profile, and under -trimpath Go keeps only
its file name, so the flag readers dropped values such as
`private-training.pgo` and split paths with spaces or commas. Report
the value whole, skipping `auto` and `off`.
* fix(audit): read -extldflags paths as the external linker splits them
With -ldflags set to -extldflags '-L "/srv/private sdk"', the outer
flag reader could not match the path behind the inner quote, and the
external reader kept only relative paths, so go.build_paths read
not_observed. Read each -extldflags value once, as go tool link splits
it with quoted.Split, and collect rooted and relative paths from those
same arguments. The rest of the setting is read as before.
* fix(audit): read the Go linker's other path options
go.build_paths read only -L as a Go linker path option, so a retained
-ldflags='-tmpdir=private-obj -s -w' reported no path and --fail_on low
missed the directory.
Read every option `go tool link -h` documents as taking a directory,
path or file: -I, -L, -benchmarkprofile, -capturehostobjs, -cpuprofile,
-fipso, -importcfg, -memprofile, -o, -r and -tmpdir. -extld, -extar and
-libgcc name a program or `none`, so only their rooted values count.
* fix(audit): keep a quoted Go argument whole
goFields already reads -L "/tmp/private - sdk" as two arguments, but
each field was then split again before every whitespace-led dash, so
go.build_paths reported /tmp/private instead of the retained directory.
Split again only a field that begins with a flag, after any package
selector, as a quoted "-L dir -s -w" does. Any other field is one
argument and is kept whole, in -ldflags, -extldflags and CGO flags.
* fix(audit): keep coverage unknown for an unread packaged image
When a listed package member is a native image but its first read
fails, examinePackagedBinary returned before probePackagedImage could
mark its possible embedded package unexamined. Coverage stayed complete
and javascript.source_map_sources could report not_observed for a
payload nobody read.
Mark member coverage unknown wherever a native member goes unread,
including an encrypted one, as an image the probe could not read
already does, and say so in the limitations.
* fix(audit): read rooted Go tool path arguments whole
`-L "/tmp/private,sdk"` and `-L=/tmp/a=b` name one directory, so a `,` or
`=` in a documented path flag's argument is literal. `-trimpath` keeps its
prefix=replacement structure.
* fix(audit): count an unread packaged member once
* fix(audit): keep trimpath rewrites and directory fields apart from selectors
* fix(audit): keep a .map unsettled once a declaration was discarded
* fix(audit): skip env option arguments when reading a Node shebang
* fix(audit): keep companion coverage unresolved for a generic .map link
* fix(audit): count a dropped linker-map guess as a skipped companion
* fix(audit): read env settings after -- in a Node shebang
* fix(audit): route a selected native image named .map by its format
A directly selected or listed native image has no package format, so
examineMember skipped its native-first branch and sent a file such as
release.map through map routing. Its bytes then became a linker-map
guess and marked native.debug_companions exposed. Native format now
outranks the name for every member, packaged or not.
* fix(audit): read forwarded -rpath and -rpath-link as linker paths
A cgo build with CGO_LDFLAGS=-Wl,-rpath,private-runtime kept the
relative directory, but the forwarded linker parser only knew -L, -T,
-I, --library-path, --dynamic-linker and --script, so go.build_paths
reported not_observed. Add -rpath and -rpath-link to the same parser,
in the attached, = and next-field forms. Loader-expanded values such as
$ORIGIN/../lib and @loader_path/Frameworks name no build-host directory
and stay unreported.
* fix(audit): read each entry of a forwarded linker search list
-rpath and -rpath-link take a colon-separated search list. The loader
token filter tested the whole list, so -Wl,-rpath,$ORIGIN:/opt/private-runtime
dropped /opt/private-runtime along with $ORIGIN, and the rooted-path pass
cannot see an entry that follows a colon. Split each search list into its
entries and drop only the loader-expanded ones.
* fix(audit): expand loader tokens only in a linker search list
The runtime loader expands $ORIGIN and @loader_path only in a -rpath or
-rpath-link search list. The token filter also ran on the argument of -T,
-L and -I, so -Wl,-T,$ORIGIN.ld dropped a literal linker script path and
a complete read could report go.build_paths as not observed. Search list
entries keep the filter; every other linker path argument is kept as is.
* fix(audit): count a .map link beside a selected file as a skipped companion
The sibling scan skipped any .map entry that was not a regular file, so a
symlink such as symbols.map -> payload beside a selected executable left
debug companion coverage at not observed. The reader never follows links,
so the linker map such a link may name is unread, not absent. Count a
generic .map sibling link as a skipped companion without following it,
as noteUnfollowedMapLink already does inside a selected directory.
* fix(audit): split a linker search list only for an ELF image
Only the ELF linker reads a -rpath or -rpath-link argument as a
colon-separated list. The Mach-O linker stores each -rpath argument as one
directory, so -Wl,-rpath,@loader_path/lib:extra is a single loader-relative
entry, yet it was split and extra was reported as a build path. Carry the
native image format into the Go flag reader and split search lists only for
ELF; other formats read the whole argument as one entry.
* fix(audit): expand only the image loader's runtime tokens
A runtime search path token is expanded only by the loader of the image's
format. The ELF loader expands $ORIGIN, $LIB and $PLATFORM; dyld expands
@executable_path, @loader_path and @rpath. Each is literal text to the
other loader, so -Wl,-rpath,$ORIGIN:/opt/private-runtime on a Mach-O image
names a literal directory, yet it was dropped and go.build_paths reported
not_observed. Pick the token set from the native image format; the PE
loader reads no search list, so it expands none.
* fix(audit): keep a declared .map link beside a selected script a source map
The sibling scan counted any .map symlink as a skipped debug companion
before checking whether the selected script declared it as its source
map. classifySiblingMap already excludes a declared target that is a
regular file, so a declared symbols.map link added a false unknown to
debug_companions. Apply the declared-target check before either file-type
branch; noteUnreachedTargets still counts the unread map as skipped.
* fix(audit): byte-check members whose kind is only an inventory path role
Inventory gives a packaged member a role from its name, such as resource
for payload.json or source-map for payload.map. The packaged-format guard
treated any kind other than "file" as owner-stated, so a nested ASAR an
ASAR lists under one of those names skipped signature recognition and
cleared coverage. Track whether the package owner stated the kind (Bun
sourcemap region, SEA main script) and only skip the byte check then.
* fix(audit): read Go's linker -r setting as a runtime search list
go tool link -r sets the ELF dynamic linker search path, dir1:dir2:...,
which the linker writes to RUNPATH. It was read as one whole path, so a
release built with -ldflags='-r=$ORIGIN/../lib' reported the
loader-relative entry as a build path and go.build_paths as exposed.
Read -r entry by entry with the same image-loader-aware split and token
filter a forwarded -rpath uses: ELF splits at ':' and drops $ORIGIN
entries; Mach-O keeps the argument as one directory.
* fix(audit): keep a selected package executable's native carrier format
A directly selected PyInstaller executable named release.map recorded the
package format as its member format, even though its ELF or PE carrier was
already recognized. examineMember then missed the native-first branch and
treated the executable as a linker map, reporting a debug companion.
Forward the native carrier format for the selected file, as listed members
already do.
* fix(audit): keep coverage unknown for an unread unclassified member
A packaged member with no format of its own, such as a PyInstaller
payload.bin, recorded only a skipped text member when its read failed
before the header. Member coverage then stayed complete, though the
member could be a native image or carry a nested package. Leave
coverage unknown and say which member could not be read, as an unread
native member already does.
* fix(audit): keep ASAR header admission distinct from max_file_bytes
A directory holding an ASAR whose header exceeds the header admission
was reported as a file-size refusal with max_file_bytes advice, which
cannot fix it. Report the header admission as its own bound instead.
* fix(audit): thread the shared ASAR header admission into release exposure
createReleaseExposureService built ReleaseExposureReader with no admission,
so its inventory and every reopened ASAR reader stayed on the 16 MiB
default and ignored REA_ASAR_MAX_HEADER_BYTES and asar.max_header_bytes.
Resolve the admission in the composition with runtimeAsarHeaderAdmission,
as the Electron and V8 observation providers do, and pass it to both
inventoryArtifactInScope calls, the reopened container readers, and the
nested ASAR signature probe. The refusal now names the setting that can
raise it instead of claiming there is no runtime override.
* fix(audit): keep a nested ASAR probe stopped at the admission undecided
The release exposure reader treated an ASAR signature probe that stopped
at the header admission as "not an ASAR". A packaged member such as
payload.json holding an ASAR whose JSON starts past asar.max_header_bytes
was then read as plain text, its inner maps went unread, and
javascript.source_map_sources could stay not_observed.
A probe that reaches the admission limit, or runs out of a prefix read
after its extents parse, now marks package coverage unknown and records
a limitation, while the member is still examined as text.
* fix(cli): parse audit-release-exposure --max-file-bytes as a decimal token
Main now requires every numeric CLI option to admit decimal tokens and
reject 0x10 and 1e3 (tests/boundary/cli/cliDecimalArguments.test.ts).
Wrap the release exposure maxFileBytes option in cliDecimalField like the
other maxFileBytes options, so the domain field keeps its bounds and default.
* docs(specs): add the release exposure audit specification
Add spec.md, plan.md and tasks.md under docs/specs/artifacts/release-exposure/
as docs/development/documentation.md requires for a new feature, and list
them in docs/specs/README.md. The existing guide at docs/release-exposure.md
keeps describing current behavior and its route is unchanged.
* fix(audit): bind unpacked ASAR member reads to their inventoried digests
A selected ASAR is captured and checked against its inventoried digest, which
binds packed members. An unpacked member is read from its .unpacked companion
on disk instead, and readContainerMember and readEntryBytes never compared
those bytes with the member digest inventory recorded, so a companion
replaced between inventory and the scan was accepted.
readContainerMember now passes the member's inventoried digest for unpacked
entries, and readStreamBounded hashes the full stream, draining past the read
allowance when needed, and fails with "ASAR member changed before
interpretation", which surfaces as an artifact_changed error like the
container check. A regression test replaces a companion after inventory. The
guide, spec, plan and tasks describe the binding.
* fix(audit): let stated JavaScript roles outrank a .map name
isDeclaredMap() routed any member whose name ended in .map to map
handling before the owner's stated role or a page's script declaration
was considered. A Node SEA main script at boot.map, which the SEA reader
marks as javascript, and a .map script an HTML file loads both became
linker-map guesses, so their inline maps were never read and
native.debug_companions was reported exposed.
An owner-stated source-map role or a declared map target still makes a
member a map. Otherwise a stated javascript kind or a script target now
wins, and only then does the .map suffix, or the inventory path role that
repeats it, decide. Regression tests cover both cases, and the guide
notes that a SEA main script is read as a script whatever it is called.
* fix(audit): keep coverage unknown when a packaged text member fails to read
A compressed member named as text, such as payload.json in an unexpanded
PyInstaller host, can fail inflation before any header is returned. The
.bin case already leaves member coverage unknown because an unread header
may hide a nested image or package, but examineTextMember() only counted
the member as skipped text, so otherwise complete coverage stayed
complete and package-dependent checks could settle.
An unread packaged member whose kind its package did not state now goes
through noteUnreadBinary(), which counts it as skipped text, marks
coverage unknown, and records the limitation. A regression test corrupts
the zlib stream of payload.json in a CArchive host and checks the intact
member keeps coverage complete. The guide describes the rule.
* fix(audit): keep the unpacked ASAR digest check inside the read allowance
ea87cf8 made readStreamBounded hash an unpacked ASAR companion to its end
so it could compare against the inventoried digest, which drained the
stream past the read allowance. A 1 GiB unpacked module was read in full
for a 4 KiB header probe and again for a package probe, and a companion
that grew after inventory had no byte limit on that path.
readStreamBounded now stops at the allowance as every other member read
does, and compares the digest only when the member ended within the
allowance. A companion past the allowance stays over_allowance without a
digest verification. A test counts the bytes each scan read pulls from an
8 MiB companion. The guide and spec state the bound.
* fix(audit): read a script target whose bytes are a source map as a map
1d3f89f let a stated javascript kind or an HTML script target outrank a
.map name, so an HTML `<script src="main.map">` that points at a valid
source map with sourcesContent was read only as a script. Its sources
were never counted and javascript.source_map_sources could miss an
exposed finding.
A script role says how a member is loaded, not what its bytes hold. A
.map member or loaded script whose text parses as a source map, a JSON
object with version and mappings, sources, or sections, is now read as
a source map. Anything else is still read as a script, so a SEA main
script named boot.map and a .map script carrying an inline map keep
reaching examineInlineMaps. A regression test covers the map case, and
the guide states the rule.
* fix(audit): retract a linker-map guess when a page loads the map as a script
noteScriptTarget() returned early for a target already read, counting its
source-map coverage as skipped but leaving any linker-map guess the first
read recorded. When a directory or ASAR listed a non-JSON app.map before
the index.html that loads it with <script src="app.map">, app.map stayed in
native.debug_companions and the result depended on enumeration order.
noteMapTarget() already retracted such a guess for a late map declaration.
A late script declaration now retracts the guess too, and still counts the
script as skipped because it was never examined as JavaScript. A test
covers the directory and ASAR order, and the guide states the outcome.
* fix(audit): respect script and native identity for sibling linker maps
classifySiblingMap() guessed a linker map for any sibling .map whose bytes
could not begin a JSON object. A sibling boot.map that a selected index.html
loads with <script src="boot.map">, or an ELF image named release.map beside
a selected executable, was therefore reported in native.debug_companions.
scanSiblings() now skips a sibling that is a script target as well as a map
target, leaving noteUnreachedTargets() to count it, and classifySiblingMap()
records no guess when sniffNativeFormat() recognizes the header. Tests cover
both cases and the guide states the outcome.
* fix(audit): read a script-loaded map from the text that recognized it
scriptHoldsMap() recognizes a .map or script target as a source map from
decodeMemberText(), which honors a UTF-16 byte order mark, but
readScriptAsMap() then passed the raw bytes to readSourceMap(), which reads
UTF-8. A BOM-marked UTF-16 main.map loaded by <script src="main.map"> failed
the second parse and its prefix became a linker-map guess.
readScriptAsMap() now hands the decoded text to readSourceMapText(), which
readSourceMap() also uses for byte input, so both stages read the same text.
A test covers a UTF-16 map with embedded sources.
* fix(release-exposure): honor byte order marks in binary plist data
A binary plist data object holding BOM-marked UTF-16 text was decoded as
UTF-8, so credential markers in it went unmatched while coverage still
read complete. Decode such payloads with the encoding their mark declares,
and leave coverage incomplete for UTF-32, which no reader scans.
* fix(audit): keep an unprobed package member past the text allowance unknown
Once the cumulative text allowance was spent, examineTextMember() counted a
packaged member named like text, such as payload.json in a .NET or
PyInstaller bundle, as skipped text without reading its header. Coverage
stayed complete even though the member could be a native image or a nested
ASAR, while the same bytes named payload.bin kept coverage unknown.
An unexpanded package member whose kind the owner did not state now leaves
coverage unknown with a limitation when the allowance skips it, the same
uncertainty an unread .bin member carries. No extra read is made, so the
allowance still bounds what is opened. A test covers an ASAR with an
embedded source map named payload.json after sixteen full text members.
* fix(release-exposure): require a read host for every Electron layout
A directory with several resources/app.asar layouts counted one named
host as fuse coverage for all of them. Track host coverage per layout so
safe fuses stay unknown when a whole layout's possible hosts were
dropped from the native image sample.
* fix(release-exposure): keep a .map script past the target allowance unassessed
When HTML script references spent the resolved-path allowance, a later
.map script target was dropped without its script role, so its JavaScript
bytes settled as a linker-map guess and debug_companions reported an
exposure. A refused script target now sets mapTargetsDiscarded, the same
flag a refused map target sets, so a later .map stays unassessed instead
of becoming companion evidence.
* fix(release-exposure): read a Node shebang as script in any text member
A selected or listed text file such as runner.txt that starts with a Node
shebang went straight to the text reader, which never gave it a JavaScript
role, so its inline map went unread and source_map_sources read
not_observed. The text reader now takes the role from the bytes it read,
so every route into it sees the shebang, and the probed-text path no longer
sets the role itself.
* fix(release-exposure): exclude Go search lists by position, not by value
compilerPaths dropped every literal path whose text equalled a forwarded
-rpath or -rpath-link list, so CGO_LDFLAGS=-Wl,-L,$ORIGIN -Wl,-rpath,$ORIGIN
lost the literal -L directory and go.build_paths read not_observed. The
literal flags are now read with each search list option and its argument
removed by position, and the search lists are still read entry by entry.
* fix(release-exposure): keep a probed Node launcher's role past the allowance
The probe recognized a Node shebang but handed the text reader the member
without its JavaScript role. Once earlier text spent the shared allowance,
the text reader returned before reading the header again, so an
extensionless launcher added no skipped map and both source-map checks read
not_observed instead of unknown. The probe now passes the role it found.
* fix(release-exposure): decode a map in the encoding its byte order mark names
The map reader, its prefix check and the sibling classifier decoded map
bytes as UTF-8, so a generic symbols.map holding BOM-marked UTF-16 source
map JSON failed to parse and its prefix read as a linker map: a spurious
debug companion and source_map_sources not_observed. Map bytes are now
decoded by their byte order mark at that boundary, and a UTF-32 map, which
this reader does not decode, stays unresolved.
* fix(release-exposure): keep a lone dash inside a quoted Go path argument
splitGoField split a quoted field before every whitespace-led dash, so the
retained -ldflags '-s "-L=/tmp/private - sdk" -w' read the dash inside the
directory as a new flag and goPaths reported /tmp/private. A quoted field
now splits only before a dash that begins a flag, so a dash followed by a
space stays part of the path.
* fix(release-exposure): choose possible Electron hosts within each layout
The named-or-possible host choice ran across every kept image, so a named
a/a.exe removed the unnamed b/launcher.exe of a second ASAR layout from
electron_host_paths, and its unresolved fuses no longer held
electron.run_as_node at unknown. Each layout now chooses its own named or
possible hosts, and the sets are combined.
* fix(release-exposure): read a relative compiler --sysroot as a build path
The compiler path flag list had no --sysroot, and the rooted-path fallback
cannot see a relative operand, so CGO_LDFLAGS=--sysroot=private-sdk left
go.build_paths at not_observed. --sysroot is now a compiler path flag,
attached with = or given as the next field.
* fix(release-exposure): recognize Windows Electron layouts by the owner's path
The desktop owner gives each file a native local_path, such as
C:\ship\App\resources\app.asar on Windows, and desktopPathConventions only
splits on /, so every ASAR basis was skipped: host ranking and
electron_host_paths stayed empty and a named host with no sentinel let a
safe helper read electron.run_as_node as not_observed. Each basis now
carries whether the owner's slash-separated path is an ASAR layout, and the
layout folders read a Windows absolute path with Windows separators on any
host.
* fix(release-exposure): read a Bun module by its JavaScript loader
An extensionless Bun contents member such as $bunfs/root/release carries
loader_name js, but ownerStatedKind kept only the sourcemap region, so the
member was never read as a script and its inline map went unseen. Give a
Bun contents region the javascript role for the js, jsx, ts and tsx
loaders, as SEA main scripts get it.
* fix(release-exposure): read a Node shebang .map as a script
An undeclared `.map` was routed as a source or linker map before its
first bytes were checked, so a Node script named `runner.map` recorded a
linker-map companion and never had its inline map read. When the map
read of an undeclared `.map` starts with a Node shebang, its map slot is
returned and the text reader examines it as JavaScript, so its inline
map is parsed and no companion is reported.
* Detect full-length GitHub refresh tokens
Narrow github.token to gh[opus]_ with 36 characters and give ghr_ its
own 76-character github.refresh_token rule, with a test.
* fix(release-exposure): bind a negative package probe to the inventoried image
An on-disk native image whose embedded-package probe finds nothing clears member coverage, so it now hashes the probed descriptor and compares it with the inventoried digest before accepting absent. A replacement after inventory fails as a changed member instead of reporting complete coverage.
* fix(release-exposure): let an app bundle read settle only its own layout
An app target, an app-bundle fuse read or a sampled selected executable used to mark the Electron executable as included for every ASAR layout, so safe outer fuses reported not_observed even when a nested Electron app's host was never read. Those reads now settle only their own layout; every other discovered layout still needs its own host read, so an omitted nested host keeps fuse checks unknown.
* fix(release-exposure): honor a Node shebang before guessing a sibling linker map
A sibling .map beside the selected file that starts with a Node shebang is a script, as it already is for a member .map, so classifySiblingMap no longer records it as a linker-map debug companion.
* fix(release-exposure): name a bundle's own layout by the owner's path
The settled layout set joined the caller's bundle spelling with Contents, so a selected /tmp/App.app missed the owner's resolved /private/tmp/App.app/Contents layout and safe fuse checks fell to unknown. Each archive basis now carries the owner's relative layout folder, and the bundle's own layout is the one whose relative folder is Contents, looked up by the owner's resolved folder.
* fix(release-exposure): read file-valued linker options as build paths
LINKER_PATH_FLAG listed --script but not the other linker options that read a file, so -extldflags=-Wl,--version-script=private-versions.map left go.build_paths not_observed. --version-script, --dynamic-list and --retain-symbols-file now read their operand as a path, attached or in the next field.
* fix(release-exposure): count a macOS bundle's framework and MacOS hosts in its layout
A .app layout resolves to its Contents folder, but its hosts are Contents/MacOS/* and the Electron framework binary under Contents/Frameworks, so per-layout host ranking and fuse coverage dropped them and one bundle's safe fuses could settle another bundle. Those images now belong to the bundle's layout, with the framework binary ranked as its host.
* fix(release-exposure): keep a bundle's launcher out of its fuse hosts
A macOS bundle's Electron Framework binary carries its fuses. When it
is among a layout's named hosts, it is now the layout's only fuse host;
the MacOS launcher beside it is still sampled but no longer leaves safe
fuse checks undecided when it has no sentinel.
* fix(release-exposure): keep an undecided PE package member out of linker maps
An unexpanded package member named .map whose PE signature lies past the
retained prefix fell through to noteUnreadMap, which read its MZ prefix as
a linker map and reported native.debug_companions exposed with complete
coverage. The map route now records the same undecided-PE uncertainty the
binary route does, so the member stays unexamined and coverage unknown.
* fix(release-exposure): scan the text of an undecided PE map member
A packaged .map member whose MZ header is undecided returned before its
fully read bytes reached the credential scanner, so a PEM key in it read
as unknown instead of exposed. Scan bytes read in full before returning,
while still keeping PE coverage undecided.
* fix(release-exposure): keep an oversized text member's undecided PE header
A packaged text member past the per-member allowance keeps only its prefix,
so an MZ header whose PE signature lies further in returned null and the
text route dropped the native and package uncertainty. Note the undecided
header as the map and binary routes do.
* fix(release-exposure): join Electron layouts by caller path and keep partial discovery unknown
The desktop owner resolves its root, so a target selected through a
symlinked parent got canonical local_paths that never matched the
audit's caller-spelled images, and the named host dropped out of
electron_host_paths. Rebase owner paths under the canonical root onto
the selected path.
When discovery stopped after it found one Electron layout, the basis
list was treated as exhaustive. Report the layouts as incomplete so safe
fuses on the listed host stay unknown.
* fix(release-exposure): keep Electron hosts under a trailing-slash selection
Join the rebased archive path with appendCallerPath so a selected
`/work/app/` yields `/work/app/resources/app.asar`, whose layout folder
matches the inventoried executables' parent.
* fix(release-exposure): keep maps unassessed for unread text past the allowance
A text-named member such as `runner.txt` can start with a Node shebang.
Once the text allowance is spent its header is not read either, so count
every unread member that could hold a script as a skipped map instead of
trusting the filename-derived role.
* fix(release-exposure): keep an unread packaged map member undecided
When a packaged map member yields no header (a failed read or no map
slot), its name is no evidence of its format. Route it through
noteUnreadBinary, as the text route does, so a member that may be a
native image or package keeps coverage unknown.
* fix(release-exposure): keep an undecided sibling PE header out of linker-map guesses
A sibling .map past the map allowance keeps only its probe, so an MZ
header whose PE signature lies further in is undecided. Share the
undecided-PE test with packaged members and count such a sibling as a
skipped companion instead of guessing a linker map.
* fix(release-exposure): keep possible fuse hosts when no ASAR layout names one
Without an ASAR basis no image is ranked, so no image counted as a fuse
host and one image's safe fuses could settle a sentinel-less sibling.
While the desktop family is undecided and no layout names a host, treat
every sampled image as a possible host.
* fix(release-exposure): keep images outside a found ASAR layout as possible fuse hosts
An asar: false build beside a discovered ASAR layout gets no basis, so
its executables were never fuse hosts and the layout's safe fuses could
settle a sentinel-less image in the other build. When no name picks out
a host outside the found layouts, treat every sampled image there as a
possible host, as the no-layout case already does while the family is
undecided.
* fix(release-exposure): keep a dropped host outside a found ASAR layout unread
An asar: false build beside a found ASAR layout names no host, so an
executable outside every layout that the native-image sample dropped may
be that build's unread fuse host. Coverage no longer counts as proven
when such an image was inventoried but not sampled.
* fix(release-exposure): read Go build-path response files named in compiler and linker flags
A CGO setting such as `-Wl,@/tmp/private-link.rsp` or
`-Xlinker @/tmp/private-link.rsp` names a response file the linker reads
options from, and a bare `@FILE` is read by the compiler driver. Report
the file's path, relative or rooted like other path arguments, without
opening it. An option's own value, such as `-install_name
@rpath/libx.dylib`, and dyld runtime tokens are not response files.
* fix(release-exposure): keep a dropped host outside an ASAR layout unread whatever its name
The guard for a sampled-out host beside a found ASAR layout ruled images
out by filename, so an asar: false host named like `b/My.App` was missed
and safe fuses from the sampled layout settled the installation. Every
inventoried native image outside the found layouts that the sample
dropped now keeps the fuse checks unknown.
* fix(release-exposure): keep maps unassessed for an unreadable extensionless launcher
An unclassified file whose initial header probe fails, such as an
extensionless `runner` that became unreadable after inventory, may carry
a Node shebang and a map directive. The probe failure now leaves its
maps unassessed, as an unread `runner.js` or packaged member does,
instead of counting the file as holding no script.
* fix(release-exposure): read a response file named like a dyld token
`-Wl,@rpath/private-link.rsp` names a linker response file, not a dyld
runtime path, so dropping every `@rpath` or `@loader_path` argument hid
it. A dyld token is now skipped only as the value of an option that takes
one, such as `-install_name` or `-dylib_file`.
* fix(release-exposure): keep the partial member scan on ordinary cancellation
A scan cancelled after some members were examined reported its partial
scan only when cleanup also failed, so a clean cancellation dropped the
recovered source-map and credential observations. A cancelled scan now
hands its assembled facts to the interrupted-scan visitor with unknown
coverage and a cancellation limitation, and the caller still receives
the cancellation error carrying that partial audit.
* docs(release-exposure): describe the partial report kept when the member scan is cancelled
Since the member scan keeps what it examined on ordinary cancellation,
the status guide no longer says that cancelling the scan returns no
partial report. It now describes the partial observation and limits the
no-report case to cancellation before the scan can be assembled.
* fix(release-exposure): keep maps unassessed when a text header is cut short
A text-named member read with one or two bytes of the text allowance
left returns only `#` or `#!`, which cannot establish a Node shebang, so
`runner.txt` kept its non-script role and its unexamined inline map was
treated as absent. A partial or missing header that could still start a
shebang line now leaves the member's maps unassessed, as an unread
member's do once the allowance is spent.
* fix(release-exposure): keep dotted executables as possible hosts in ASAR layouts
Inside an ASAR layout, a sibling whose name had a dot and no `.exe`
suffix, such as `my.app`, was neither ranked for the native sample nor
counted as a possible Electron host. With shared libraries filling the
sample, that image could be dropped while the layout still counted its
host as read, so safe fuses on a helper reported `run_as_node` as not
observed. A dotted sibling that is not named like a shared library is
now sampled after plain siblings and counted as a possible host.
* fix(release-exposure): split env -S shebangs on unquoted blanks only
The env shebang reader split the whole line on spaces before handling -S,
so a launcher such as `#!/usr/bin/env -S NODE_OPTIONS='--conditions
development' node` named `development'` as its program and its maps were
never assessed. An -S operand now takes the rest of the line and is split
the way GNU env -S splits it: single and double quotes, backslash escapes,
\_ and \c, and a leading # comment. A string env itself rejects, such as an
unterminated quote, runs no program.
* fix(release-exposure): keep owner facts completed before cancellation
When a Go, Rust, fuse or desktop owner finished its Evidence and then saw
cancellation, completeProviderEvidence returned that Evidence as the
error's partial observation, but the audit only kept the error and
substituted a not-run fact, so a recovered Go build path or Rust package
list reported unknown. Each owner's Evidence-to-fact reading now lives in
one function used for both a successful read and a completed partial, so
the partial passes the same schema and inventory digest checks before its
fact is kept. Later owners still do not run.
* fix(release-exposure): keep env -S programs named by a variable unassessed
`env -S` expands `${NAME}` from the environment, so a launcher such as
`#!/usr/bin/env -S ${NODE_BIN}` may run Node, but the shebang reader kept
the placeholder as the program name and treated the file as plain text,
reporting its inline map as absent. The env splitter now marks fields that
expand a variable, and a program whose name holds one leaves the shebang
undecided: the member's maps count as unassessed, and a `.map` companion
with such a header is not taken as a linker map. Quoted or escaped `${`
stays literal, and a resolved basename such as `${DIR}/bin/deno` still
decides.
* fix(release-exposure): keep the ASAR header admission for selected files
A directly selected app.asar whose header exceeds asar.max_header_bytes
now returns the typed header admission refusal and its recovery, as the
directory scan already does, instead of a generic partial report.
* fix(release-exposure): keep a map member with a variable env -S program unassessed
An undeclared `runner.map` whose `env -S` program is `${NODE_BIN}` may
run Node, so `examineMapMember` now treats an undecided `nodeShebang`
result as an unassessed map and companion, as `classifySiblingMap`
already does, rather than falling through to a linker-map guess.
* fix(release-exposure): read a forwarded -Map linker map path
splitForwardedLinkerFlags hands -Wl,-Map=private-link.map to the linker
side, but LINKER_PATH_FLAG had no Map entry, so the relative map path was
dropped and go.build_paths read not_observed. Add Map to the file-valued
linker options so -Map=FILE and -Map FILE are both reported.
* fix(release-exposure): count unread text in undecided map branches
An oversized .map whose shebang names its program with an unresolved
variable, or a package member with an undecided PE header, returned
before counting its unscanned text, so credential markers could read
not_observed. Count any non-bytes read as skipped text in both branches.
* fix(audit): bound map reads and preserve linker paths
* fix(audit): retain unread package uncertainty
* fix(audit): retain ambiguous linker operands
* fix(audit): preserve compiler path separators
* fix(audit): retain distinct linker map occurrences
* fix(audit): apply map declarations to their exact source path
A declaration recorded only its NFC lookup key, so every member or
sibling sharing that key took the declared JavaScript-map route. On a
normalization-sensitive filesystem an unrelated linker map spelled in
another form lost its companion evidence when the declaring script was
scanned first.
Record the resolved spellings each declaration writes and treat only an
exact match as declared. Another spelling in the bucket is read as an
undeclared map; when no declared spelling is reached, its linker-map
guess stays unresolved coverage rather than companion evidence.
* fix(audit): keep partial inventory from settling fuse-host coverage
When a directory read found ASAR layouts but the inventory stopped
early, a separate asar: false build outside those layouts may never
have been listed. Only sampled-then-dropped images counted as a
possible missed host, so reading every found layout's host reported
safe fuses as not_observed for the whole selection.
In limitNativeSample, treat an incomplete inventory as a possible
missed host outside the found layouts unless the read root is itself
a found layout, where host identity already settles coverage.
* fix(audit): apply script targets to their exact source path
A page's script element was recorded only by its NFC lookup key, so on
a normalization-sensitive filesystem a distinct file spelled in another
normalization form inherited the JavaScript role. An unrelated linker
map such as café.map beside a loaded café.map was never classified
and debug companion coverage could settle as not observed.
Keep the resolved spellings each page wrote under the lookup key, as map
declarations already do, and give the script role only to a member or
sibling whose exact path a page loaded.
* fix(audit): keep partial inventory uncertain beside a root ASAR layout
When the read root was itself a found ASAR layout, an incomplete
inventory was trusted to have listed every possible fuse host. A second
asar: false build under a subdirectory names no layout and sits outside
the root layout, so an inventory that stopped after the root host could
miss its launcher and still report the root's safe fuses as
not_observed. The same launcher, once listed, already kept the result
unknown.
Drop the root-layout exemption in limitNativeSample so any incomplete
inventory beside a found layout keeps fuse-host coverage unknown. A
complete inventory that lists only the named host still settles.
* fix(audit): read the linker's --just-symbols file operand
A Go build that forwarded -Wl,--just-symbols=private.syms through
-extldflags or CGO_LDFLAGS kept the relative symbol file in its build
settings, but the forwarded linker matcher knew only the short -R
spelling. Complete metadata then reported go.build_paths as
not_observed while the equivalent -R build was exposed.
Add --just-symbols to the linker options that read a file. Only -R
turns into -rpath when given a directory, so the $ORIGIN ambiguity
check stays on the short spelling.
* fix(audit): anchor expanded package members to the selected path
An inventory-expanded package member reports its location relative to
the selected path, such as app.asar/boot.map, but its lookup identity
resolved that location against the process working directory. An
on-disk page loading app.asar/boot.map, or an absolute file: map
declaration into the archive, resolved under the selected root, so the
declaration never matched the member it named. A script target with an
inline map then settled as a linker map, and a declared map stayed
skipped.
Resolve every member lookup and declaration base against the selected
path, and keep the reported location as written. Linker-map retraction
compares the same anchored spelling.
* fix(audit): read GCC's -I- include barrier as an option
CGO_CFLAGS=-I- is GCC's include barrier, the same as --include-barrier,
not -I with the directory "-". The compiler path matcher read it as a
build path, so a Go binary retaining it reported go.build_paths exposed.
Skip that exact field before path matching.
* fix(audit): keep packaged-image uncertainty after reading the host
A native image stored inside a package is never opened by a fuse reader,
so reading the Electron host on disk does not settle its fuses. Count the
packaged omission toward a partial fuse sample on its own, so safe host
implications stay unknown instead of not_observed while a packaged image
is unread.
* fix(audit): require every named host in a layout to be sampled
An ASAR layout can name more than one host, such as `a/a.exe` beside
`a/electron.exe`. The sample counted the layout as read when any one
named host was kept, so dropping the other still reported the Electron
executable as included and let safe fuses from the sampled images settle
run_as_node as not_observed. Count a layout as read only when every host
it could have was sampled, reusing the named-host selection the fuse
reducer already applies.
* fix(audit): keep a layout-less bundle read from settling partial inventory
A bundle with no ASAR layout, such as an asar: false build, counted its
framework read as covering the Electron host even when inventory stopped
early or the sample dropped an image. A nested build's host could sit in
the part never listed, so the root framework settled RunAsNode as
not_observed. Apply the same incomplete-inventory guard the layout branch
uses to the bundle read.
* fix(audit): read the linker's --sysroot directory operand
A Go ELF build that forwarded -Wl,--sysroot=private-sdk through
-extldflags or CGO_LDFLAGS kept the relative sysroot in its build
settings, but the forwarded linker matcher did not know the option.
Complete metadata then reported go.build_paths as not_observed, while
the compiler-owned --sysroot was already recognized.
Add --sysroot to the linker options that take a path, so the -Wl comma
form, the -Wl = form and both -Xlinker forms are read.
* test(audit): group Deno boundary regressions
* fix(audit): preserve Go linker file operands
* fix(audit): track script completion per source occurrence
* refactor(audit): give Go path parsing one semantic owner
* refactor(audit): preserve map roles at the parsing boundary
* refactor(audit): consume toolchain operands once
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
1583 lines
85 KiB
Markdown
1583 lines
85 KiB
Markdown
# CLI and Evidence
|
||
|
||
Use the CLI for a direct inspection or a script. It uses the same application
|
||
workflows and evidence contracts as REA's MCP server. Each CLI invocation is a
|
||
separate process; save results when you want to use them in a later command.
|
||
For a pinned, noninteractive workflow with retained reports, see
|
||
[static analysis in GitHub Actions](../ci-analysis.md).
|
||
|
||
## Run a command
|
||
|
||
After [installing REA](installation.md), use `rea`. You can also run a command
|
||
without a global installation:
|
||
|
||
```bash
|
||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||
```
|
||
|
||
Use an extracted application directory or an ASAR as the target. Static
|
||
JavaScript analysis returns the application graph and Evidence directly.
|
||
Generic `rea analyze PATH` selects this workflow for directories and `.asar`
|
||
files when neither `--provider` nor `--snapshot` is supplied. See
|
||
[JavaScript artifact reconstruction](../guides/javascript/javascript-artifact-reconstruction.md)
|
||
for results, integrity checks and coverage.
|
||
|
||
The complete application Evidence can be hundreds of megabytes for a real
|
||
application. When an agent or a person reads the result, save it to a file and
|
||
project a summary, a module page or one module from the saved Evidence:
|
||
|
||
```bash
|
||
rea analyze-javascript-application /absolute/path/to/app --json > app-evidence.json
|
||
jq -c '{source: {kind: "inline", evidence: .}, view: {kind: "summary"}}' app-evidence.json > app-view.json
|
||
rea inspect-analysis-view app-view.json
|
||
```
|
||
|
||
The request can also name the saved file instead of embedding it:
|
||
`{"source": {"kind": "evidence-file", "path": "app-evidence.json"}, "view": {"kind": "summary"}}`.
|
||
The CLI resolves a relative path against the working directory; MCP clients
|
||
pass an absolute path. REA reads and authenticates the file, then projects it
|
||
like retained Evidence, so a large file is bounded by the file reader rather
|
||
than charged as inline input.
|
||
|
||
An argument that accepts inline JSON or a JSON file path also accepts `-`, which
|
||
reads the request from standard input, so a generated request needs no
|
||
temporary file:
|
||
|
||
```bash
|
||
jq -nc '{source: {kind: "evidence-file", path: "app-evidence.json"}, view: {kind: "summary"}}' | rea inspect-analysis-view -
|
||
```
|
||
|
||
Standard input is read once as a single UTF-8 JSON document without a
|
||
byte-order mark, and it is limited to 8 MiB. Put a larger request in a file.
|
||
|
||
Local file inspection commands reject empty paths and NUL bytes before resolving
|
||
relative inputs, auxiliary files or output destinations. An empty string never
|
||
selects the working directory; use an explicit `.` when selecting that directory
|
||
is supported by the command.
|
||
|
||
For example, a 334 MB Obsidian application Evidence file yields a summary view
|
||
of about 10 KB. Replace the view with
|
||
`{"kind": "page", "collection": "modules", "offset": 0, "limit": 32}` for a
|
||
module page. See
|
||
[JavaScript application workflows](../guides/javascript/javascript-application-workflows.md) for
|
||
views, feature traces and comparisons that take the same saved Evidence.
|
||
|
||
Add `--timings` to a command to write one JSON timing record to stderr. For
|
||
example, `rea inspect-elf-notes program --json --timings > result.json` keeps
|
||
stdout as a parseable result and writes
|
||
`{"rea_timings":{"version":1,"command_ms":42}}` to stderr. `command_ms`
|
||
measures CLI command dispatch and result delivery; it is not provider-only or
|
||
analysis-only time. The flag is off by default, and the record omits stages
|
||
that REA did not measure. Root version reporting does not dispatch a command
|
||
and has no command timing record.
|
||
|
||
## JSON Lines record output
|
||
|
||
Use `--format jsonl` to consume row-oriented results one record per line:
|
||
|
||
```bash
|
||
cat > observations-view.json <<'JSON'
|
||
{"source":{"kind":"evidence-file","path":"app-evidence.json"},"view":{"kind":"javascript-facts","property_keys":[],"offset":0,"limit":32}}
|
||
JSON
|
||
rea inspect-analysis-view observations-view.json --format jsonl > observations.jsonl
|
||
```
|
||
|
||
This request selects up to 32 observation identities and their provenance,
|
||
without observation property values.
|
||
|
||
This changes JSONL object-collection framing. Scripts that need one complete
|
||
report or a scalar field should use `--format json`. For a full application
|
||
graph, first project a supported analysis view rather than selecting an
|
||
arbitrary nested graph array.
|
||
|
||
A top-level array emits its elements in source order. An object must have one
|
||
clear `rows`, `items`, `records`, or `occurrences` array, directly or under
|
||
`page`. Evidence uses the same boundaries inside `normalized_result`.
|
||
Any other selection is refused before a record is written, including an
|
||
arbitrary report, a scalar, a nested array elsewhere, and a columnar object such
|
||
as the `inspect-sqlite-database --table` `normalized_result.rows`
|
||
(`{columns, values}`). The refusal is the caller error `invalid_request`
|
||
(`invalid_input`) and names the selection and its observed shape; the analysis
|
||
itself succeeded, so use `--format json` for the complete document. If several
|
||
collections exist, select one with `--filter-output`, for example
|
||
`normalized_result.rows` for an analysis view.
|
||
|
||
Object collections finish with a control record:
|
||
|
||
```json
|
||
{
|
||
"$rea": "jsonl/v1",
|
||
"type": "metadata",
|
||
"records": {
|
||
"path": ["normalized_result", "rows"],
|
||
"emitted": 2,
|
||
"source": 10,
|
||
"filter": "normalized_result.rows[0,2]"
|
||
},
|
||
"context": {
|
||
"evidence_id": "ev_…",
|
||
"normalized_result": {
|
||
"coverage": {
|
||
"status": "page",
|
||
"examined": 10,
|
||
"total": 100,
|
||
"next_offset": 10,
|
||
"exhausted": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
This abbreviated example illustrates framing. The actual `context` preserves
|
||
all non-row fields, including Evidence subject, provider, authority, confidence,
|
||
locations, links, limitations, parent/view digests, pagination and coverage.
|
||
With `--full-output`, it also retains the command envelope and its metadata.
|
||
A data filter selects row fields/slices while this context remains available;
|
||
excluded peer record collections and unselected Evidence `raw_result` are not
|
||
restored. An explicitly selected `raw_result` remains selected. Retain the
|
||
original Evidence for complete observations.
|
||
|
||
`records.emitted` and `records.source` count the selected output and its source
|
||
array; they do not assert analysis completeness. Source coverage and unknowns
|
||
retain their original meaning. Existing row identities and indices remain
|
||
unchanged unless your field selection excludes them. Empty object collections
|
||
still emit metadata; an empty top-level array emits no lines. Bare top-level
|
||
arrays have no synthetic coverage record.
|
||
|
||
Command and output-validation failures emit `{"$rea":"jsonl/v1","type":"error","ok":false,"result":…}`
|
||
and retain the original diagnostic payload. SDK validation/sentinel errors use
|
||
the SDK's exit status rather than guessing from data fields. `$rea` is reserved
|
||
at the top level of a data record, so control records are unambiguous; collisions
|
||
are refused before rows are written. Nested `$rea` values are ordinary data.
|
||
A missing final metadata record or nonzero exit can indicate an interrupted
|
||
export; do not treat already emitted rows as a complete result.
|
||
|
||
`--token-count` estimates this exact representation, including metadata, one
|
||
line at a time. Errors remain error records even with token counting enabled.
|
||
Token windows cannot preserve JSON Lines and are rejected. JSON encoding and
|
||
stdout writes are incremental, including large escaped strings; this is output
|
||
streaming over a completed result, not incremental analysis. The analysis still
|
||
needs its normal resources. A single record must fit the runtime string limit
|
||
for token estimation; remove `--token-count` to stream a larger record.
|
||
|
||
Standalone version and MCP doctor diagnostics remain single JSON documents
|
||
in JSON Lines mode. Incur's streaming generator events and successful sentinel
|
||
responses retain their SDK protocol. MCP application results and Evidence
|
||
contracts are unchanged.
|
||
|
||
## Shell completion
|
||
|
||
The CLI includes optional shell completion. Run `rea completions --help` to
|
||
see the available shells and their setup commands. For Bash, load the hook
|
||
into the current shell:
|
||
|
||
```bash
|
||
eval "$(rea completions bash)"
|
||
```
|
||
|
||
For zsh, initialize completion before loading the hook. If your shell already
|
||
runs `compinit`, place the hook after that existing initialization:
|
||
|
||
```zsh
|
||
autoload -Uz compinit
|
||
compinit
|
||
eval "$(rea completions zsh)"
|
||
```
|
||
|
||
The Bash hook supports macOS system Bash 3.2. It uses optional completion
|
||
features when the shell provides them and falls back to portable registration.
|
||
Completion includes standard global options and the active command's options;
|
||
`rea mcp ` offers only `add` and `doctor`. Output-option values remain data when
|
||
resolving the command scope.
|
||
|
||
For future interactive non-login Bash sessions, add the command to
|
||
`~/.bashrc`. Interactive login Bash sessions read the first available file in
|
||
`~/.bash_profile`, `~/.bash_login`, and `~/.profile`; add the command to the
|
||
file your shell reads, or have that file source `~/.bashrc`. Remove the command
|
||
from the startup file to stop loading completion, and run `complete -r rea` to
|
||
remove the registration from the current shell. These are manual, opt-in
|
||
steps.
|
||
Completion is a discovery aid; use `rea COMMAND --help` to confirm the
|
||
available options and subcommands.
|
||
|
||
## Managed assemblies (.NET)
|
||
|
||
For a .NET PE/CLI assembly, inspect its identity and deployment form before
|
||
inspecting members. These commands read metadata and Common Intermediate
|
||
Language (CIL) without loading or executing the assembly and require no native
|
||
analysis engine:
|
||
|
||
```bash
|
||
rea inspect-managed-artifact /absolute/path/Assembly.dll --json
|
||
rea inspect-managed-members /absolute/path/Assembly.dll --json
|
||
rea inspect-managed-members /absolute/path/Assembly.dll --type Example.Parser --json
|
||
```
|
||
|
||
Replace `Example.Parser` with an exact `full_name` from the member inspection,
|
||
or a declaring type name you already know. Omit `--type` to inspect all members,
|
||
or repeat it to select several types.
|
||
Selection limits decoding to the selected types; member references remain an
|
||
assembly-wide inventory, so the output can still be large.
|
||
|
||
Select `--detail summary --evidence-bundle /absolute/path/members.json` to
|
||
receive identity, selection, coverage, limitations and collection counts while
|
||
saving the complete original Evidence in a new bundle. Summary requires that
|
||
explicit destination; existing files are preserved. Later
|
||
`inspect-analysis-view` calls can page the exact parent from the saved bundle
|
||
without reopening the assembly. See
|
||
[CLI summary and saved member rows](../guides/managed/managed-code-analysis.md#cli-summary-and-saved-member-rows)
|
||
for the complete command sequence. Omitted or `--detail complete` retains the
|
||
full inline response.
|
||
|
||
Choose the workflow from the artifact's contents rather than its `.exe` or
|
||
`.dll` extension. The managed parser requires PE/CLI metadata; it does not
|
||
unpack .NET single-file hosts or decode IL2CPP. For the image, type and method
|
||
names in a Unity `global-metadata.dat`, use
|
||
[IL2CPP metadata](../il2cpp-metadata.md). NativeAOT method bodies require native
|
||
analysis. See the [managed-code guide](../guides/managed/managed-code-analysis.md)
|
||
for supported deployment forms, selection semantics, and coverage limits.
|
||
|
||
## SQLite snapshots
|
||
|
||
For a local database snapshot, use `rea inspect-sqlite-database PATH --json`.
|
||
Add `--table NAME --row-limit 20` to read a bounded sample from an ordinary
|
||
table. This command does not require a native analysis provider. See
|
||
[SQLite database snapshots](../guides/data/sqlite-databases.md) for database/WAL identity,
|
||
source-file handling and row-value semantics.
|
||
|
||
## Native analysis
|
||
|
||
Inspect embedded Go build metadata without installing Go or configuring a
|
||
disassembler:
|
||
|
||
```bash
|
||
rea inspect-go-binary /absolute/path/to/program --json
|
||
```
|
||
|
||
The shared CLI/MCP workflow reports compiler version, modules, replacements,
|
||
build settings, original bytes and SHA-256. See [Go binaries](../guides/native/go-binaries.md)
|
||
for supported containers and absent or malformed metadata.
|
||
|
||
Inspect a Godot PCK without running the game:
|
||
|
||
```sh
|
||
rea inspect-artifact game.pck --detail summary --evidence_output evidence.json --json
|
||
rea extract-artifact game.pck --json
|
||
```
|
||
|
||
Formats 2, 3 and 4 retain header, directory and integrity facts. Compact delivery
|
||
keeps complete Evidence in the requested bundle. See [Godot PCK](../godot-pck.md)
|
||
for embedded packs, batch queries and unknown encrypted coverage.
|
||
|
||
Inspect a UnityFS AssetBundle without running Unity:
|
||
|
||
```sh
|
||
rea inspect-artifact content.bundle --detail summary --evidence_output evidence.json --json
|
||
rea extract-artifact content.bundle --json
|
||
```
|
||
|
||
Format versions 6 through 8 retain header, block and directory facts with
|
||
none/LZ4/LZ4HC block decompression. See [UnityFS](../unityfs.md) for encryption
|
||
and LZMA coverage boundaries.
|
||
|
||
Inspect a WeChat mini-program package without WeChat or an unpacker:
|
||
|
||
```sh
|
||
rea inspect-artifact app.wxapkg --detail summary --evidence_output evidence.json --json
|
||
rea extract-artifact app.wxapkg --json
|
||
```
|
||
|
||
Plaintext packages retain header, table and member facts with verbatim member
|
||
bytes. `V1MMWX` packages are detected as encrypted coverage and refused on
|
||
extraction. See [wxapkg](../wxapkg.md) for layout and coverage boundaries.
|
||
|
||
Inspect an ESP32-family app or bootloader image without esptool:
|
||
|
||
```sh
|
||
rea inspect-artifact firmware.bin --json
|
||
rea extract-artifact firmware.bin --json
|
||
```
|
||
|
||
The inventory lists each segment with its ESP-IDF load classification, the
|
||
checksum and SHA-256 results, the descriptor and any Secure Boot v2 signature
|
||
blocks. See [ESP images](../esp-image.md) for recognition, coverage and refusals.
|
||
|
||
Inspect an ESP flash dump, or one read from a flash address other than 0:
|
||
|
||
```sh
|
||
rea inspect-artifact flash.bin --json
|
||
rea inspect-artifact dump.bin --target-format esp-flash-image --flash-offset 0x1000 --json
|
||
rea extract-artifact flash.bin --json
|
||
```
|
||
|
||
The inventory lists the bootloader, the partition table and each partition,
|
||
with ESP image facts for app partitions and the OTA records. See
|
||
[ESP flash images](../esp-flash-image.md) for table location, inputs and limits.
|
||
|
||
Inspect a Node.js SEA carrier without running it:
|
||
|
||
```sh
|
||
rea inspect-artifact ./application --json
|
||
rea extract-artifact ./application --json
|
||
```
|
||
|
||
See [Node.js SEA](../node-sea.md) for supported layouts, script and asset paths,
|
||
fuse observations, and the real-fixture verification lane.
|
||
|
||
Inventory and extract Intel HEX or S-record regions:
|
||
|
||
```sh
|
||
rea inspect-artifact ./firmware.hex --json
|
||
rea extract-artifact ./firmware.hex --json
|
||
```
|
||
|
||
See [Intel HEX and S-record images](../hex-records.md) for recognition, region
|
||
names, metadata and limits.
|
||
|
||
Inspect and extract stored U-Boot legacy uImage payloads and components:
|
||
|
||
```sh
|
||
rea inspect-artifact ./firmware.bin --detail summary --evidence_output firmware.json --json
|
||
rea extract-artifact ./firmware.bin --json
|
||
```
|
||
|
||
See [U-Boot uImage](../uimage.md) for verified CRCs, physical component ranges,
|
||
unknown names, resource limits and retained views. Compressed bytes stay stored.
|
||
|
||
`inspect-artifact` and `extract-artifact` also read ZIP members compressed with
|
||
Zstandard (standard method 93). They retain the shared ZIP CRC, declared-size,
|
||
overlap and archive expansion checks. The native streaming decoder keeps the
|
||
existing 128 MiB Zstandard window cap; frames requiring a larger window are
|
||
reported as a resource limit (`reason: limit`, `boundary: memory`), rather than
|
||
as archive corruption. The cap cannot be raised at runtime: recompress with a
|
||
window of at most 128 MiB, or decompress externally before retrying.
|
||
Deprecated method 20 and other unregistered ZIP codecs remain unsupported.
|
||
|
||
Inventory and extract UF2 or DfuSe regions:
|
||
|
||
```sh
|
||
rea inspect-artifact ./firmware.uf2 --json
|
||
rea extract-artifact ./firmware.dfu --json
|
||
```
|
||
|
||
See [UF2 and DfuSe images](../uf2-dfuse.md) for recognition, families, numbering,
|
||
the DfuSe suffix CRC and limits.
|
||
|
||
Inventory and extract U-Boot FIT images:
|
||
|
||
```sh
|
||
rea inspect-artifact ./boot.itb --json
|
||
rea extract-artifact ./boot.itb --json
|
||
```
|
||
|
||
See [U-Boot FIT images](../fit-images.md) for recognition, data sources, hashes
|
||
and limits.
|
||
|
||
Inspect local model declarations without loading weights:
|
||
|
||
```bash
|
||
rea inspect-model-artifact /absolute/path/model.gguf --json
|
||
rea inspect-model-artifact /absolute/path/model.safetensors --hash full --json
|
||
```
|
||
|
||
Default hashing reads only headers and leaves full-file identity unknown.
|
||
`--hash full` streams the complete file for SHA-256. Both return typed metadata,
|
||
original tensor declarations and derived totals. MCP summaries retain complete
|
||
Evidence for filtered metadata, tensor and type-total pages; CLI compact delivery
|
||
uses `--detail summary --evidence_output FILE`. See [model files](../model-artifacts.md).
|
||
|
||
Inspect Unity IL2CPP metadata names without Unity or a disassembler:
|
||
|
||
```bash
|
||
rea inspect-il2cpp-metadata /absolute/path/global-metadata.dat --json
|
||
```
|
||
|
||
The command decodes a version 24, 27, 29, 31 or 39 `global-metadata.dat` and reports assembly
|
||
images, type, method and member names, string literals, index ranges, header
|
||
sections and SHA-256. With `--binary PATH` it also reads the matching
|
||
`GameAssembly.dylib`, `GameAssembly.dll` or `libil2cpp.so` (never runs it) and
|
||
links each method to its code address; `--generic-instances` adds generic
|
||
method instances and `--ghidra-seeds PATH` then writes Ghidra function seeds. It does not decrypt metadata. MCP defaults to compact counts
|
||
with retained Evidence; query indexed rows with filters, batch indices and
|
||
selected fields. The CLI defaults to complete Evidence;
|
||
`--detail summary --evidence_output FILE` exports the full result to a new file
|
||
and returns a compact overview. See [IL2CPP metadata](../il2cpp-metadata.md).
|
||
|
||
Inspect an embedded cargo-auditable Rust dependency list without installing
|
||
Rust or configuring a disassembler:
|
||
|
||
```bash
|
||
rea inspect-rust-binary /absolute/path/to/program --json
|
||
```
|
||
|
||
The same workflow reports package names, versions, sources, the root package,
|
||
dependency edges, and the section's file range. A missing `.dep-v0` section is
|
||
null metadata, not proof that the binary has no dependencies. See
|
||
[Rust binaries](../rust-binaries.md).
|
||
|
||
Inspect a PE Authenticode certificate table without executing the image or
|
||
verifying signatures:
|
||
|
||
```bash
|
||
rea inspect-pe-certificates /absolute/path/to/application.exe --json
|
||
```
|
||
|
||
The workflow reports `WIN_CERTIFICATE` entries and, for PKCS#7 signedData,
|
||
embedded X.509 serial, issuer, subject, and validity fields. A missing security
|
||
directory is observed absence of that table. See
|
||
[PE Authenticode certificate tables](../pe-certificates.md).
|
||
|
||
Inspect PE import and delay-load tables without executing the image:
|
||
|
||
```bash
|
||
rea inspect-pe-imports /absolute/path/to/application.exe --json
|
||
```
|
||
|
||
The workflow reports DLL names, named and ordinal functions, delay-load
|
||
descriptors, and a pefile-compatible import hash of the standard import table.
|
||
A missing import directory is observed absence of that table. See
|
||
[PE import and delay-load tables](../pe-imports.md).
|
||
|
||
Inspect a Windows Shell Link (`.lnk`) without resolving or executing the
|
||
target:
|
||
|
||
```bash
|
||
rea inspect-windows-shortcut /absolute/path/to/shortcut.lnk --json
|
||
```
|
||
|
||
The workflow reports header flags and FILETIMEs, IDList items, LinkInfo volume
|
||
and network names, StringData arguments and icon location, ExtraData blocks
|
||
including Tracker droid facts labelled derived, and derived observations such
|
||
as argument length and a minimized ShowCommand. See
|
||
[Windows Shell Link shortcuts](../guides/native/windows-shortcut.md).
|
||
|
||
Inspect ELF PT_NOTE and SHT_NOTE tables without executing the image:
|
||
|
||
```bash
|
||
rea inspect-elf-notes /absolute/path/to/program --json
|
||
```
|
||
|
||
The workflow reports note owners, types, descriptor hashes, and GNU build-id
|
||
or ABI-tag fields when those descriptors match. A missing note table is
|
||
observed absence of those declarations. See [ELF note tables](../elf-notes.md).
|
||
|
||
List ELF and Mach-O initializer and finalizer functions without executing the
|
||
image:
|
||
|
||
```bash
|
||
rea inspect-native-initializers /absolute/path/to/program --json
|
||
```
|
||
|
||
The workflow reports `DT_INIT`, init/fini arrays, legacy `.ctors`/`.dtors`, and
|
||
Mach-O `__mod_init_func`, `__init_offsets` and `__mod_term_func` entries with
|
||
their resolved targets. Universal Mach-O files need `--architecture`. See
|
||
[ELF and Mach-O initializer functions](../guides/native/native-initializers.md).
|
||
|
||
Inspect ELF unwind function ranges without executing the image:
|
||
|
||
```bash
|
||
rea inspect-elf-unwind-ranges /absolute/path/to/program --json
|
||
```
|
||
|
||
The workflow reports FDE start, end, and size, the containing section, an exact
|
||
symbol name when one exists, CIE identity, LSDA, and personality. Coverage
|
||
counts ranges that match a symbol, ranges without a symbol, and whether the
|
||
`.eh_frame_hdr` search table agrees with the decoded FDEs. `.debug_frame` is
|
||
reported present, absent, or incomplete and is not decoded. A missing unwind table is
|
||
observed absence of those declarations. See
|
||
[ELF unwind function ranges](../guides/native/elf-unwind-ranges.md).
|
||
|
||
Inspect an Apple `.ips` crash report without executing a target:
|
||
|
||
```bash
|
||
rea inspect-apple-ips /absolute/path/to/report.ips --json
|
||
```
|
||
|
||
The workflow reports first-line metadata, process/exception/termination facts,
|
||
threads, usedImages, lossless integer registers, and documented crash classes
|
||
when `bug_type` is `"309"`. Other DiagnosticReports types return no crash
|
||
result. See [Apple IPS crash reports](../apple-ips.md).
|
||
Inspect Linux kernel module metadata without executing the module or requiring
|
||
`modinfo`:
|
||
|
||
```bash
|
||
rea inspect-kernel-module /absolute/path/to/module.ko --json
|
||
```
|
||
|
||
The workflow reports ordered `.modinfo` keys (duplicate `alias` and `parm`
|
||
entries preserved), `__versions` symbol CRCs, presence of
|
||
`.gnu.linkonce.this_module` and `__ksymtab` sections, observed `.init.text`
|
||
and `.exit.text` sizes, and an appended signature trailer. `struct module` is
|
||
not decoded and the signature is not validated. Other ELF types are not
|
||
applicable. gzip, xz, and zstd containers are unsupported and name
|
||
`external_decompression` as the next probe: decompress with an external
|
||
utility, then inspect the decompressed file. See
|
||
[Linux kernel modules](../kernel-modules.md).
|
||
|
||
Read a Linux kernel image's version banner and embedded `CONFIG_IKCONFIG`
|
||
build config without executing it:
|
||
|
||
```bash
|
||
rea inspect-kernel-build-config /absolute/path/to/vmlinux --json
|
||
rea inspect-kernel-build-config /absolute/path/to/bzImage --name CONFIG_MODULE_SIG --json
|
||
```
|
||
|
||
The workflow reports the banner version, builder, and compiler, the config
|
||
option count, and paged `CONFIG_*` entries (`y`, `m`, strings, numbers, and
|
||
`not_set`). An `IKCFG_ST` string counts as a config only when a valid gzip
|
||
member follows it and `IKCFG_ED` follows that member. A gzip bzImage payload
|
||
is inflated and searched; other payload codecs are unsupported and name
|
||
`external_decompression` as the next probe. See
|
||
[Linux kernel build config](../guides/native/kernel-build-config.md).
|
||
|
||
Inspect a CPython 3.7–3.13 `.pyc` header and nested marshal code objects (3.14 and
|
||
3.15 headers are qualified but their marshal layout is not pinned)
|
||
without executing bytecode or installing Python:
|
||
|
||
```bash
|
||
rea inspect-python-pyc /absolute/path/to/module.pyc --json
|
||
```
|
||
|
||
The workflow reports the pinned CPython version for the magic, PEP 552 hash or
|
||
mtime/size fields, nested function names, and bytecode SHA-256. Bytecode is
|
||
not decompiled. See [CPython pyc inspection](../python-pyc.md).
|
||
|
||
Inspect an Erlang BEAM file without executing bytecode:
|
||
|
||
```bash
|
||
rea inspect-erlang-beam /absolute/path/to/app.beam --json
|
||
```
|
||
|
||
The workflow reports IFF chunk names, atom tables, exports, imports, lambdas,
|
||
and the Code chunk header. Missing optional tables stay null. See
|
||
[Erlang BEAM files](../erlang-beam.md).
|
||
|
||
Complete `rea decompile --json` Evidence can be saved and inspected through
|
||
`inspect-analysis-view` with an inline source and
|
||
`view: {kind: "native", facet: "pseudocode", offset: 0, limit: 20000}`.
|
||
The projection reads that saved observation without starting a provider;
|
||
offsets/limits count UTF-16 code units. A summary view preserves the original
|
||
selector and distinguishes null from empty text. The MCP tool additionally
|
||
supports `detail: "summary"` on its first call to retain the complete source
|
||
without returning the body inline; see [native investigation](../guides/native/native-investigation.md).
|
||
|
||
Configure [Hopper or Ghidra](installation.md#hopper), the
|
||
[IDA adapter](../providers/ida-provider.md), or [Kuna](../kuna-provider.md) before analyzing a
|
||
native target. Substitute
|
||
your target, search text and function name or address in these examples:
|
||
|
||
```bash
|
||
rea analyze /absolute/path/to/program --provider ghidra --json
|
||
rea search /absolute/path/to/program "search" --provider ghidra --json
|
||
rea function /absolute/path/to/program main --provider ghidra --json
|
||
rea decompile /absolute/path/to/program 0x1000 --provider ghidra --json
|
||
rea xrefs /absolute/path/to/program 0x1000 --provider ghidra --json
|
||
rea trace /absolute/path/to/program "search" --provider ghidra --json
|
||
```
|
||
|
||
`analyze` and `inspect` share the native overview workflow. `function` returns
|
||
a function dossier; `decompile` returns pseudocode. For assembly instructions
|
||
alone, use `rea instructions`. A macOS `.app` bundle can be supplied directly.
|
||
|
||
A complete dossier can reach several megabytes of value-flow and references.
|
||
`rea function ... --detail summary --evidence_output /absolute/path/dossier.json` returns the
|
||
compact summary and saves the complete dossier as an Evidence bundle, never
|
||
overwriting an existing file. Page that bundle without reanalysis by naming it
|
||
as an `inspect-analysis-view` source, selecting the summary's
|
||
`normalized_result.parent_evidence_id` when the bundle holds several records:
|
||
`{"source": {"kind": "evidence-file", "path": "/absolute/path/dossier.json", "evidence_id": "ev_…"}, "view": {"kind": "native", "facet": "pseudocode", "offset": 0, "limit": 4096}}`.
|
||
MCP `analyze_function` defaults to the same summary and retains the complete
|
||
dossier in the session for `inspect_analysis_view`.
|
||
|
||
Run `rea --help` or a command's `--help` for arguments and output options.
|
||
The [generated catalog](../reference/mcp-contracts.md#generated-catalog) lists all CLI commands and MCP
|
||
tools. Provider-specific target support is described in the
|
||
[native guide](../guides/native/native-investigation.md), [DOS guide](../providers/ghidra-dos.md),
|
||
[raw binary guide](../providers/raw-binary.md), [GameCube DOL guide](../ghidra-dol.md), and
|
||
[Windows Ghidra guide](../providers/windows-ghidra-p0.md).
|
||
|
||
## Choose a provider
|
||
|
||
List the available providers and their supported operations:
|
||
|
||
```bash
|
||
rea providers --json
|
||
rea capabilities --json
|
||
```
|
||
|
||
These commands describe binary-session providers and auxiliary capabilities.
|
||
For the complete MCP surface, use the connected server's tool list and the
|
||
session's advertised availability; individual guides describe prerequisites.
|
||
|
||
With automatic selection, REA uses the single available provider that supports
|
||
the target. When several providers support it, select one explicitly:
|
||
|
||
```bash
|
||
rea analyze /absolute/path/to/program --provider hopper
|
||
```
|
||
|
||
Set `REA_ANALYSIS_PROVIDER` for a standing preference. An explicit `--provider`
|
||
overrides it. In MCP, pass `provider_id` to `open_binary`:
|
||
|
||
```json
|
||
{
|
||
"path": "/absolute/path/to/program",
|
||
"provider_id": "hopper"
|
||
}
|
||
```
|
||
|
||
The selected provider remains bound to the session until an explicit switch
|
||
or close. Provider failures are returned with their original reason. For an
|
||
`ambiguous` selection error, choose from `details.candidate_ids`; for
|
||
`provider_unavailable`, follow `message`, `remediation.action`, and the original
|
||
reasons in `details.rejections`. Each rejection names its `origin`: `availability`
|
||
entries describe local readiness failures, including missing configuration or an
|
||
invalid existing registration; they do not establish target support. `target`
|
||
entries record a refused kind, format, architecture, or role. An availability-only
|
||
message describes the recorded rejections without claiming that every provider
|
||
is unconfigured or that target support is known.
|
||
For Hopper, Ghidra, IDA, JADX, and Kuna, run
|
||
`rea doctor --provider ID --json` to diagnose the selected engine. Other adapters,
|
||
such as `pwntools-elf`, report their configuration requirements directly and are
|
||
not accepted by `doctor --provider`. See
|
||
[task readiness](installation.md#check-readiness-for-your-task) and
|
||
[provider selection](../reference/mcp-contracts.md#identity-and-discovery).
|
||
|
||
The session reports work still in progress through `analysis_activity`.
|
||
A client timeout can end its wait while the provider continues analyzing.
|
||
`cleanup_incomplete` identifies resources whose shutdown or removal could not
|
||
be verified. See [MCP contracts](../reference/mcp-contracts.md) for session lifecycle and
|
||
[Ghidra first-query deadlines](../reference/mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
|
||
for import, client timeouts and recovery.
|
||
|
||
One-shot binary analysis validates the selected operation's input before creating
|
||
a provider session, opening the target, or replaying a snapshot. Invalid selectors
|
||
and option combinations report their input errors before target or provider
|
||
availability errors. An already-cancelled request keeps its cancellation reason.
|
||
Caller-selected paths and request parameters remain separate from parsed execution
|
||
arguments in Evidence.
|
||
|
||
A one-shot command attempts provider-session and runtime cleanup before reporting
|
||
a failure. If cleanup remains incomplete, inspect the reported resources and
|
||
follow the error's remediation. [Same-session cleanup retry](../reference/mcp-contracts.md#retained-cleanup-retry),
|
||
reuse and `update_analysis_settings` apply to a live MCP connection.
|
||
For one-shot commands, `details.limit` reports `scope: "rea-invocation"` and
|
||
`applies_at: "next_invocation"`; set the named `environment` (or the per-call
|
||
`parameter`) for a new invocation and rerun. For example, a Ghidra decompile
|
||
deadline names `REA_GHIDRA_DECOMPILE_TIMEOUT_SECONDS`.
|
||
|
||
`rea debug-with-gdb` and `rea debug-with-rizin` hold their debugger only for the
|
||
command's own process. If cleanup cannot confirm the debugger stopped, they print
|
||
`cleanup_incomplete` and exit nonzero without stopping it. `remediation.action`
|
||
names the process, as does `retained_debugger_pids` in `details.diagnostics`, or
|
||
in `details.diagnostics.cleanup_error.details.diagnostics` when the command also
|
||
failed or was interrupted. Exiting closes the debugger's command and output pipes.
|
||
REA does not establish what the debugger or its target does next, so check that
|
||
process. An MCP server that shuts down likewise exits with status 1 instead of
|
||
waiting on a debugger it could not stop. It names the process on stderr and as
|
||
`retained_debugger_pids` in its error log.
|
||
|
||
If one-shot analysis fails and closing its session also fails, the original
|
||
error details remain inline and `details.cleanup_error` describes the later
|
||
close failure. Each diagnostic retains its own reported resources; the later
|
||
failure does not establish whether an earlier resource was released. Captured
|
||
output and partial observations remain in the original details.
|
||
|
||
## Save and reuse analysis snapshots
|
||
|
||
A snapshot retains successful analysis results for later queries. REA reuses
|
||
an exact result when the target bytes, operation, parameters, provider and
|
||
settings match. Mutations and cursor-dependent calls are excluded from the
|
||
cache. Snapshot files are local and use owner-only permissions.
|
||
|
||
A binary CLI replay reports the current invocation's selected path while leaving
|
||
the saved Evidence and snapshot query unchanged. See
|
||
[caller-selected paths](../reference/mcp-contracts.md#caller-selected-paths)
|
||
for primary and auxiliary path fields and their relation to Evidence identity.
|
||
|
||
Importing an Evidence bundle refreshes retained request and subject display metadata.
|
||
It preserves cached analysis results, including observations for other targets.
|
||
Snapshot bindings that use a replaced record retain its updated display path.
|
||
|
||
Dispatching a provider metadata write invalidates the active session's snapshot cache,
|
||
even if its reply fails: the provider may already have applied the write.
|
||
Close and reopen the target before importing or saving another snapshot.
|
||
|
||
Saved snapshots include only cache entries whose subject identifies the selected
|
||
target. Unbound observations and observations of child artifacts remain available
|
||
in the open session and its Evidence bundle; they are excluded from the target's
|
||
saved replay entries without changing their subjects.
|
||
The snapshot also retains available Evidence linked by selected records, including
|
||
transitive sources with an unbound or different subject. Those sources are not
|
||
replay entries for the selected target. Unrelated records remain excluded.
|
||
|
||
Snapshots retain eligible target-scoped question histories in full, including
|
||
mutation Evidence recorded while another target was active. Observations and
|
||
related questions must still belong to the saved target. If those dependencies
|
||
cannot be retained, the entire history is excluded instead of reverting the
|
||
question to an earlier revision or disposition.
|
||
|
||
```bash
|
||
rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program.json
|
||
# Repeat the same query to reuse its saved result.
|
||
rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program.json
|
||
```
|
||
|
||
An exact CLI cache hit is normally read before starting a provider process.
|
||
`decompile --provider ghidra --snapshot ...` also retains its single selected
|
||
Program's pseudocode result, even without an explicit document selector. Old
|
||
snapshots that contain only the Evidence need one new query to add that replay
|
||
entry. This does not retain every body from `decompile-all` or make a persistent
|
||
session's implicit document replayable.
|
||
On Windows, Ghidra first admits the selected source through its native snapshot
|
||
owner, so replay can start that provider.
|
||
In MCP, `open_binary` accepts `snapshot_path` to import a snapshot atomically
|
||
for its matching target; an MCP provider may still start before returning a
|
||
cached result. `close_binary` accepts `snapshot_path` and optional
|
||
`overwrite: true` to save before releasing provider resources. A failed save
|
||
leaves the session open so the caller can resolve the output failure.
|
||
|
||
When a validated snapshot does not match the selected binding, the error's
|
||
`details.binding_mismatch` reports confirmed target identities, provider
|
||
identities, or profile digests that differ. `snapshot` is the saved value and
|
||
`selected` is the requested value. Multiple differences can be reported. A
|
||
`profile_comparison: "not_compared"` means the profile was not available at
|
||
that boundary; it does not establish a match. A profileless snapshot can report
|
||
`workflow_scope: "incompatible"` even when its target and profile match.
|
||
Choose a matching target, provider, and profile, or analyze without the snapshot
|
||
and save a new one for the intended binding.
|
||
|
||
For a profile mismatch, the saved snapshot contains
|
||
`binding.analysis_profile.parameters`. If `binary_session` reports an active
|
||
profile whose digest matches `binding_mismatch.profile_digest.selected`, its
|
||
`analysis_provider_binding.analysis_profile.parameters` can be compared with
|
||
those saved parameters. A rejected switch leaves the previous session active,
|
||
so its profile may be different from the attempted selection; check the digest
|
||
before using it for this comparison. A configuration difference does not by
|
||
itself establish why analysis results differ.
|
||
|
||
If no target is open and you intend to inspect the selected binding, open that
|
||
target without the snapshot, then check its profile digest in `binary_session`
|
||
before comparing parameters. This may start the selected provider; the saved
|
||
snapshot remains a separate file.
|
||
|
||
If a selected snapshot's file descriptor cannot close, `open_binary` reports
|
||
`cleanup_incomplete`. `binary_session` reports `cleanup_pending` even when no
|
||
target opened. Retry `close_binary` to release the retained descriptor before
|
||
opening another target.
|
||
|
||
If a snapshot switch fails after the previous target was retired, restoration
|
||
keeps that target's analysis commitments with the replacement client. This
|
||
includes the native dispatch workflow profile on a profileless route, so its
|
||
existing snapshot and fresh observations retain the same provenance.
|
||
|
||
For native dispatch, the snapshot binding retains the reader profile; workflow
|
||
Evidence and `workflow_entries` retain the composed profile, which commits that
|
||
reader and the workflow's analysis caveats. Restoration preserves both profiles.
|
||
|
||
The MCP save receipt reports `primitive_entries`, `workflow_entries`, and
|
||
`evidence_records` separately. Zero primitive bindings can still accompany retained workflow
|
||
results and Evidence. These are cached observations, not a saved provider
|
||
database: only eligible exact queries can reuse a result, and new or live
|
||
queries can still require provider startup. The CLI uses the same snapshot
|
||
format and preserves these records when loading and updating it.
|
||
When an MCP session replays a provider observation, its delivered Evidence identifies
|
||
the original observation through `evidence_links` and reports that the
|
||
provider was not rerun. The original and its available source records remain
|
||
in the investigation bundle.
|
||
|
||
## Import, export and compare Evidence
|
||
|
||
Evidence records retain artifact identity, source locations, observations,
|
||
inferences and unresolved findings. Validate an existing bundle, export its
|
||
canonical form, or compare two supplied bundles:
|
||
|
||
```bash
|
||
rea evidence-import /absolute/path/to/evidence/bundle.json
|
||
rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
|
||
rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json
|
||
rea compare left.json right.json --record_pairs '[{"left_evidence_id":"ev_<left-sha256>","right_evidence_id":"ev_<right-sha256>"}]' --json
|
||
```
|
||
|
||
Migration: replace `rea compare-bundles` with `rea compare`; the former command
|
||
has been removed. The MCP tool remains `compare_bundles`.
|
||
|
||
`rea evidence-import` performs process-local bundle authentication and
|
||
validation, reporting record and Unknown-revision counts. `unknowns_added`
|
||
counts revisions, not distinct Unknown IDs. It does not retain records in a
|
||
separate or background MCP server process. To retain records across calls in an
|
||
active MCP session, use the MCP tool `import_evidence_bundle` in that session.
|
||
|
||
`rea compare` compares records by Evidence identity and explicit pairs. It does
|
||
not read artifact contents: the inventories of two builds are unresolved
|
||
records, or one opaque change when you pair them. Use `compare-artifacts`,
|
||
described at the end of this section, to compare their contents.
|
||
|
||
`--record_pairs` accepts an inline JSON array or the path to a local JSON
|
||
file containing that array, matching MCP `compare_bundles.record_pairs`. For a
|
||
file, use `rea compare left.json right.json --record_pairs pairs.json --json`.
|
||
Pair IDs must exist on their named sides and be one-to-one. Without pairs,
|
||
one-sided membership remains unknown; REA does not infer correspondence from
|
||
position or display names.
|
||
|
||
Exports preserve an existing destination unless `--overwrite` is explicit.
|
||
|
||
Atomic Evidence output stages on the selected destination's filesystem. If the
|
||
OS pathname ceiling prevents its internal staging name, REA retries in a shorter
|
||
ancestor on that same filesystem and removes the unused stage. Existing output
|
||
protection still applies. A genuine pathname refusal uses `resource_constraint`
|
||
with `details.reason: path-limit` and `boundary: filesystem-path`.
|
||
|
||
For application traces and version comparisons, see
|
||
[JavaScript application workflows](../guides/javascript/javascript-application-workflows.md).
|
||
MCP [retained Evidence references](../reference/mcp-contracts.md#retained-application-evidence-inputs)
|
||
belong to one connection. Separate CLI calls can consume full saved records or
|
||
resolve exact retained IDs from an explicitly selected local bundle:
|
||
|
||
```bash
|
||
rea trace-application-feature request.json --evidence-bundle /absolute/path/evidence.json --json
|
||
```
|
||
|
||
Here `request.json` uses the same logical Evidence input as MCP, for example
|
||
`"application": {"kind":"retained-evidence","evidence_id":"ev_<64 lowercase hex characters>"}`.
|
||
Inline records and references may be mixed in the request's declared source
|
||
fields, including arrays and nested inputs. The bundle is read and authenticated
|
||
once for that command; no target is reopened, no producer is rerun, and no
|
||
record is selected by file order. Source identity, provenance, coverage and
|
||
partial or unknown facts agree with the complete inline form. When starting
|
||
from summary or inspection Evidence, select its
|
||
`normalized_result.parent_evidence_id` for a workflow requiring complete source
|
||
facts. Omit `--evidence-bundle` when all sources are inline.
|
||
|
||
The JSON workflow commands supporting this option are:
|
||
|
||
- `trace-application-feature`, `trace-javascript-semantics`,
|
||
`compare-application-versions`, `compare-javascript-export-shapes`,
|
||
`compare-source-to-bundle`, and `reconcile-javascript-runtime`.
|
||
- `import-managed-reconstruction`, `verify-managed-native-boundaries`, and
|
||
`project-managed-application-graph`.
|
||
- `project-android-application-graph`, `project-apple-application-graph`, and
|
||
`project-harmony-application-graph`.
|
||
- `compare-wasm-interfaces` and `inspect-analysis-view`.
|
||
|
||
For `inspect-analysis-view`, the request's source reference selects a parent
|
||
from the bundle for every supported view kind. Bundles exported from MCP work
|
||
for these commands. Its inline source form cannot also select a bundle.
|
||
A missing ID is refused with `details.reason: "missing"`;
|
||
supplying a bundle does not make incompatible Evidence valid for a workflow.
|
||
`compare-managed-members` keeps its two assembly paths and an optional
|
||
repeatable `--type` selection applied to both sides, and
|
||
`compare-process-captures` keeps its two capture Evidence JSON paths. The bundle
|
||
option above selects an input; producer options that write a new bundle, such
|
||
as `inspect-managed-members --evidence-bundle`, retain their existing meaning.
|
||
File selectors remain available only on contracts that explicitly support them.
|
||
|
||
Compare two artifact inventories with `compare-artifacts`. It takes the same
|
||
`left` and `right` input as MCP `compare_artifacts`: complete Evidence, or an
|
||
`evidence-file` source with an optional `evidence_id` that selects one record
|
||
from a bundle. Relative paths resolve from the working directory:
|
||
|
||
```bash
|
||
rea inspect-artifact old.zip --json > old.json
|
||
rea inspect-artifact new.zip --json > new.json
|
||
rea compare-artifacts '{"left":{"kind":"evidence-file","path":"old.json"},"right":{"kind":"evidence-file","path":"new.json"}}' --json
|
||
```
|
||
|
||
A one-shot `compare-artifacts` command keeps no session Evidence, so it refuses a
|
||
`retained-evidence` source with `details.reason: "missing"`. Select the record
|
||
from a saved bundle instead.
|
||
For an artifact summary selected from a bundle, include its complete parent
|
||
inventory in the same bundle. The command resolves that parent from the
|
||
authenticated file records; a summary-only file cannot supply missing facts.
|
||
|
||
## Import historical source
|
||
|
||
Historical source inventories preserve exact filenames, including literal backslashes
|
||
on POSIX hosts. Relative import lookup uses the recorded source file's owning
|
||
directory and decodes URL percent escapes once; encoded slash, NUL and malformed
|
||
escapes remain unresolved. A decoded backslash remains part of a filename rather
|
||
than a directory separator. This inventory lookup does not claim that Node can
|
||
load that filename or apply Node's runtime file-URL admission policy.
|
||
|
||
Import an older source tree to compare with the current artifact:
|
||
|
||
```bash
|
||
rea import-reference-source /absolute/path/to/source
|
||
rea import-reference-source /absolute/path/to/source --detail summary --outline-depth 2 --json
|
||
rea import-reference-source /absolute/path/to/source --exclude-paths '["vendor/","*.generated","!keep.generated"]'
|
||
```
|
||
|
||
The default (`--detail full`) returns the complete `HistoricalSourceGraph`.
|
||
Choose `--detail summary` for a `HistoricalSourceSummary` of that same committed
|
||
inventory: its `HistoricalSourceManifest` contains the semantic graph and root
|
||
digests, with provenance, VCS facts, languages, manifest paths, entry and
|
||
relationship counts, parse-failure counts, file/directory states, exclusions
|
||
and limitations. The summary is a presentation view, not a graph accepted by
|
||
source-to-bundle comparison; keep the full output for that workflow.
|
||
|
||
Known filesystem failures commit the operation, parsed errno, entry-relative
|
||
location and recovery guidance. Entry `local_diagnostics`, when present,
|
||
retains the exact host message, including local paths, outside the semantic
|
||
graph commitment. Equivalent permission failures therefore retain their manifest
|
||
identity after relocation while preserving original source diagnostics in full
|
||
output and visible summary outline entries. Other substantive limitations still
|
||
participate in the graph commitment.
|
||
|
||
An unreadable child directory remains a partial inventory entry. Directory-scoped
|
||
ignore policy is required before enumerating a directory that can be opened;
|
||
an unreadable or invalid policy still fails the import. Project negations cannot
|
||
override defaults or caller exclusions; caller patterns retain their own ordered
|
||
negations. Configured secret exclusions remain final.
|
||
|
||
`--outline-depth` requires `--detail summary` and accepts a nonnegative safe
|
||
integer. Depth 1 shows root children, depth 2 (the default) also shows their
|
||
children, and depth 0 omits all outline entries. Paths retain canonical Unicode
|
||
code-point order. `outline.omitted_entry_count` counts only inventoried entries
|
||
hidden by the chosen depth; it does not count unexamined children of excluded or
|
||
unreadable directories, or change `inventory_state`. Exclusions and source
|
||
limitations remain separate from this presentation omission.
|
||
|
||
`file_sizes.known_bytes` is the exact sum of known inventoried file sizes as
|
||
decimal text, so large sums cannot lose integer precision. Unknown sizes count
|
||
in `file_sizes.unknown_file_count`; excluded or unexamined paths are not included
|
||
in that total. A zero known-byte sum therefore does not establish an empty source
|
||
tree. Full output retains individual file hashes, relationships and parse-failure
|
||
diagnostics. Summary mode performs the same import and cleanup, then projects
|
||
the committed result without rereading source files. It reduces the selected
|
||
output, not the amount of source examined. A shallow tree or many exclusions can
|
||
still produce a large summary; depth 0 removes the outline but preserves the
|
||
other facts. No fixed output-size or runtime improvement is promised.
|
||
|
||
Import failures use the shared error contract (`code`, `category`, `message`,
|
||
`retryable`, and `remediation`). When reads completed before failure,
|
||
`details.diagnostics.partial` retains the reader facts, with file bytes as
|
||
arrays of byte values. Unresolved cleanup uses `cleanup_incomplete` and
|
||
retains the source failure and resource paths in `details`.
|
||
|
||
The import records hashes and metadata for the supplied files, separately
|
||
from observations of the current app. For a directory inside a Git checkout,
|
||
it records the HEAD of the nearest enclosing repository; whether the working
|
||
tree matches that commit remains unknown. Root selection follows filesystem
|
||
symlink/parent semantics before canonical identity is derived. It honors
|
||
`.gitignore` files at the selected root and in traversed child directories,
|
||
with patterns relative to their containing directory and deeper negations
|
||
applied only when the parent was not excluded. Matching uses the nearest
|
||
repository's local `core.ignorecase` setting (false when unset), including the
|
||
shared configuration of linked worktrees. Policy and Git metadata reads retain
|
||
their descriptor cleanup under the import's resource owner; unreadable policy
|
||
is a typed failure, not an empty policy. Above-root `.gitignore` files, global
|
||
excludes, `.git/info/exclude`, config includes and worktree-specific config are
|
||
not loaded. The import also applies default exclusions for common generated and dependency paths such
|
||
as `node_modules/`, `dist/`, and `*.log`. Pattern-based exclusions record the
|
||
matched pattern and whether it came from project, default, caller, or sensitive
|
||
path policy. Links into excluded paths retain their internal target metadata;
|
||
the exclusion explains why the target has no inventory entry, and the inventory
|
||
remains partial. Exclusions record `entry_kind` when the importer observed it;
|
||
older saved exclusions without that field have unknown kind. An excluded
|
||
ancestor proves an internal descendant only when its kind is `directory`.
|
||
Set `REA_REFERENCE_SECRET_PATTERNS_JSON` to a JSON array of ignore
|
||
patterns when you want to mark selected paths as sensitive; those patterns are
|
||
reported separately as configured-secret exclusions.
|
||
|
||
Re-import saved graphs whose pattern-based exclusions lack `pattern` before
|
||
using them in source-to-bundle comparisons.
|
||
|
||
Entries that change during an import retain an unavailable-entry diagnostic
|
||
alongside readable siblings. If enumeration of an already admitted root fails,
|
||
the graph keeps its observed children and records the root failure as a
|
||
top-level limitation. That partial inventory does not establish absence among
|
||
unexamined children. POSIX directory-entry bytes that are not valid UTF-8 cannot
|
||
be represented as graph paths; the containing directory (or root) is marked
|
||
unsupported, and REA does not access the entry through a replacement-character
|
||
name. Symlink targets are read as bytes too: a target that is not valid UTF-8
|
||
is retained as an unreadable symlink with its bytes reported in the limitation,
|
||
and is never resolved through a replacement-character path. Readable siblings
|
||
remain inventoried.
|
||
|
||
JavaScript and TypeScript import parsing requires valid UTF-8. Malformed source
|
||
bytes retain their original hashes and sizes with a decoding diagnostic; REA
|
||
does not infer module targets from replacement characters. Exact dynamic-import
|
||
strings, expression-free templates and runtime-transparent TypeScript wrappers
|
||
retain their targets; computed imports remain unknown. TypeScript import-equals
|
||
dependencies remain `requires` relationships whether or not they are exported.
|
||
Historical dependencies also include TypeScript import types (`import("./dep").T`
|
||
and `typeof import("./dep")`) and declarations inside ambient module bodies;
|
||
these source relationships do not assert runtime loading. Language labels retain
|
||
the conventional case-sensitive `.C` (C++) and `.M` (Objective-C++) suffixes.
|
||
|
||
REA derives historical CommonJS paths only when the selected loader and its
|
||
base are proven: this includes the exact
|
||
`createRequire(new URL("./file.cjs", import.meta.url))` form and
|
||
`require.resolve` with `{ paths: [__dirname] }`. Exact optional-call forms such
|
||
as `require.resolve?.("./dep.cjs")` use the same loader and mutation facts. The
|
||
nearest inventoried package manifest supplies `.js`/`.ts` package facts to the
|
||
shared parser; explicit filename modes take precedence. A known ES module has no
|
||
implicit CommonJS wrapper, including when a factory is derived from an unbound
|
||
`require`. An unreadable, excluded or malformed manifest, or package scope outside
|
||
the selected inventory, leaves otherwise unproven loader resolution unknown with
|
||
the requested specifier and a reason. A nearest manifest without a `type` field
|
||
uses the shared parser's JavaScript module-syntax facts. Unresolved TypeScript,
|
||
JSX compilation and declaration contexts do not establish runtime wrapper bases.
|
||
Other custom bases and search options remain partial with unknown resolution and
|
||
the literal requested specifier. Overwritten resolver methods retain that uncertainty; they are not
|
||
attributed to Node. `require.main` is a module object, so calling it does not
|
||
establish a loader reference. These relationships do not establish execution;
|
||
Node's [`require.resolve`](https://nodejs.org/docs/v24.22.1/api/modules.html#requireresolverequest-options)
|
||
performs lookup without loading the target. An excluded `package.json`
|
||
also leaves package-directory selection unknown rather than treating the
|
||
manifest as absent and applying an `index` fallback.
|
||
|
||
Import requests use URL pathname semantics: query and fragment remain request
|
||
identity, percent escapes decode exactly once for inventory lookup, and encoded
|
||
separators or malformed escapes retain an unresolved relationship and diagnostic.
|
||
URL-bearing relationships retain the authored `source_specifier` separately from
|
||
the inventoried `to` path; distinct query/fragment requests remain distinct even
|
||
when they name the same file. CommonJS requests retain literal filename semantics
|
||
for percent signs, query marks and fragments.
|
||
|
||
Historical-source import requires safe no-follow file opens on Linux or
|
||
macOS. Native Windows returns `unsupported_host`; use Linux REA inside WSL
|
||
or another supported host. See
|
||
[source-to-bundle comparison](../guides/javascript/javascript-application-workflows.md#historical-source-to-bundle-comparison)
|
||
for mapping identities, inferences and unknowns.
|
||
|
||
## Capture runtime behavior
|
||
|
||
Choose the guide for the target and intended interaction:
|
||
|
||
- [Browser observation](../guides/web/browser-observation.md): inspect a selected page through CDP.
|
||
- [Browser scenarios](../guides/web/browser-scenario-contract.md): run declared interactions and capture their results.
|
||
- [Electron observation](../guides/javascript/electron-observation.md): inspect an Electron renderer or capture an application scenario.
|
||
- [Electron fuses](../electron-fuses.md): read packaged fuse bytes before expecting `--inspect` to reach an Electron main process.
|
||
- [Node/Electron Inspector](../guides/javascript/javascript-runtime-observation.md): record script locations and execution contexts.
|
||
- [Process capture](../guides/runtime/process-capture.md): run an executable and compare terminal, exit and filesystem observations.
|
||
- [Desktop application capture](../desktop-application-capture.md): launch a Linux desktop application and record its windows and home-directory state at checkpoints while it is used.
|
||
- [Desktop application state](../desktop-application-state.md): read a capture folder into the application's state files, typed views of each version and kinds of change.
|
||
- [Desktop application export](../desktop-application-export.md): write a capture folder as an agentenv computer app bundle with its class, skill and seed.
|
||
- [Desktop application tasks](../desktop-application-tasks.md): describe how a capture's files changed, then validate an agent-written task against the capture and export it with its verifier.
|
||
|
||
Runtime requests name the target and actions. Launched targets run with your
|
||
user permissions; consult the chosen guide for host requirements and effects.
|
||
|
||
## Serve MCP over streamable HTTP
|
||
|
||
`rea mcp` speaks stdio to the client that launched it. To serve the same MCP
|
||
catalog over streamable HTTP for one local client, such as an agent environment
|
||
runtime, start the dispatcher entry with `--http`:
|
||
|
||
```sh
|
||
rea mcp --http --port 8765
|
||
```
|
||
|
||
`--host` and `--port` default to `MCP_HOST` and `MCP_PORT` from the environment,
|
||
then to `127.0.0.1` and an ephemeral port. A bind outside loopback requires
|
||
`MCP_ALLOWED_HOSTS` or `--allowed-hosts`, a comma-separated list of client host
|
||
names or IP addresses without URLs or ports.
|
||
|
||
Repeat `--allowed-hosts` to append names, or put multiple names in one
|
||
comma-separated value. All occurrences are validated together and deduplicated
|
||
after hostname normalization; the explicit list replaces `MCP_ALLOWED_HOSTS`.
|
||
|
||
For example:
|
||
|
||
```sh
|
||
rea mcp --http --host 0.0.0.0 --allowed-hosts 127.0.0.1,rea.lan
|
||
```
|
||
|
||
Requests with a different `Host` or browser `Origin` receive `403`; a missing
|
||
`Origin` is accepted. The announced client URL uses the bound hostname when
|
||
admitted, otherwise the first declared hostname, with the actual bound port.
|
||
It is written to stderr as one JSON log line (`"msg":"MCP transport listening"`) whatever `REA_LOG_LEVEL`
|
||
is set to; nothing is written to stdout. `rea mcp --http --help` lists the accepted options. The listener serves
|
||
one client at a time: a session ends with the client's `DELETE`, and a client
|
||
that connects while another session is open takes it over, so a client that
|
||
exited without ending its session needs no restart. The listener runs until
|
||
SIGINT or SIGTERM and does not stop when stdin closes. See
|
||
[transports](../reference/mcp-contracts.md#transports) for the session, `Host` header and
|
||
shutdown contract. Client registrations written by setup and the MCP registry
|
||
entry keep stdio.
|
||
|
||
## Serve an environment manifest
|
||
|
||
`rea environment-serve <manifest.json> --evidence <capture.json>
|
||
[--replay-only] [--host H] [--port N]` serves an environment manifest
|
||
projected by `inspect-analysis-view` as an agent environment: an MCP server at
|
||
`/mcp`, the environment card at `/.well-known/agent-env.json`, and a
|
||
`/agentenv` data plane. The manifest's `parent_evidence_id` must equal the
|
||
evidence file's `evidence_id`; otherwise the command refuses with
|
||
`invalid_request` before binding. Before binding it derives the
|
||
`environment-state` view of the capture with the manifest's `template_rules`,
|
||
as `inspect-analysis-view` would, and serves from it: read tools whose views
|
||
are state-backed answer from a live state, write tools are served only where
|
||
the capture's later reads confirmed their effect, and
|
||
`/agentenv` serves `data/reset`, `data/add` and `data/get`. When the state
|
||
cannot be derived, or its catalog exceeds the discovery reservation, it logs a
|
||
warning with the error code and message and serves replay; `--replay-only` serves replay without deriving. In replay every
|
||
manifest tool replays the retained capture records it cites and `/agentenv`
|
||
answers every method with JSON-RPC `-32601`. The stopped document's `state`
|
||
member is `{"served": true, "evidence_id": …}`,
|
||
`{"served": false, "reason": "replay-only"}` or
|
||
`{"served": false, "reason": "unavailable", "code": …, "message": …}`; see
|
||
[serve from the state](../agent-environments.md#serve-from-the-state).
|
||
|
||
```sh
|
||
rea environment-serve manifest.json --evidence capture.json --port 8765
|
||
```
|
||
|
||
`--host` and `--port` resolve like `rea mcp --http`: flags, then `MCP_HOST` and
|
||
`MCP_PORT`, then `127.0.0.1` and an ephemeral port. A non-loopback bind requires
|
||
`MCP_ALLOWED_HOSTS` with the same hostname rules and Host/Origin gates as above.
|
||
`environment-serve` uses this environment setting; `--allowed-hosts` belongs to
|
||
`rea mcp --http`. For example:
|
||
|
||
```sh
|
||
MCP_ALLOWED_HOSTS=127.0.0.1,rea.lan rea environment-serve manifest.json --evidence capture.json --host 0.0.0.0
|
||
```
|
||
|
||
`ENVIRONMENT_NAME` renames
|
||
the served environment; set but blank, it is refused as `configuration_invalid`
|
||
like a blank `MCP_HOST`. The admitted client URL is written to stderr as one JSON log line
|
||
(`"msg":"MCP transport listening"`). See
|
||
[agent environments](../agent-environments.md) for what the state and replay
|
||
return and do not establish.
|
||
|
||
## Build an environment bundle
|
||
|
||
`rea environment-build <capture> [dir] [--name <name>] [--template-rule <rule> ...]
|
||
[--format-rules-only] [--package-tarball <path>] [--capture-timeout-ms <ms>] [--dry-run]` builds the bundle
|
||
`environment-export` writes from one recorded capture: a `.har` file, which it
|
||
inspects as `inspect-web-network-capture` does, or capture Evidence JSON from
|
||
`inspect-web-network-capture` (HAR) or `capture-browser-scenario`. It projects
|
||
the environment manifest from the in-memory Evidence with the opt-in rules
|
||
`after-uid-literal`, `opaque-token`, `sibling-variance` and `prefix-variance`
|
||
unless `--template-rule` or `--format-rules-only` selects others, prepares the
|
||
state, and writes the bundle; every file is byte-identical to the three-step
|
||
path's when that path lists the same rules in the views' order and exports
|
||
under the build's name. A loopback or IP-literal capture is named after its file unless `--name`
|
||
is given. It prints one JSON report: the capture and manifest identities, the
|
||
state, a `coverage` summary of which tools answer from the state, which replay
|
||
and why each write is withheld with a hint, the files, warnings and the next
|
||
command. `--dry-run` writes nothing and may omit the directory.
|
||
|
||
```sh
|
||
rea environment-build grafana.har ./grafana --json
|
||
```
|
||
|
||
See [agent environments](../agent-environments.md#build-a-bundle-in-one-step)
|
||
for the report, the hints and what the bundle ships.
|
||
|
||
## Export an environment bundle
|
||
|
||
`rea environment-export <manifest.json> --evidence <capture.json> <dir>
|
||
[--package-tarball <path>] [--name <override>]` writes the same manifest and
|
||
capture pair as a bundle folder the agentenv framework runs with
|
||
`agent-env run <dir>`. It reads each file once, authenticates and cross-checks
|
||
the pair with the same checks as `environment-serve`, checks the bundle name,
|
||
then prepares the state under that name as the bundle's server will at startup
|
||
to predict what the bundle serves (replay when the state is unavailable),
|
||
copies the bytes it authenticated, refuses to write into a directory that
|
||
exists and is not empty, and never overwrites a file.
|
||
|
||
```sh
|
||
rea environment-export manifest.json --evidence capture.json ./grafana-example --json
|
||
```
|
||
|
||
The folder holds a `README.md` with the bundle's provenance, an env folder
|
||
`envs/<name>/` with a `Dockerfile` that installs this exact `rea-agents`
|
||
version and serves the copied `manifest.json` and `evidence.json` (written
|
||
with mode `0600` on POSIX; Windows retains inherited ACLs) with
|
||
`environment-serve` (from the state by default), a Python verifier under
|
||
`artifacts/check_<name>/` that checks the served tool count and one served
|
||
answer, and the smoke task `tasks/smoke.json`. `--package-tarball` copies a packed `rea-agents`
|
||
tarball into the env folder and installs it instead of the registry package,
|
||
which is how the hosted lane proves a checkout rather than a release. `--name`
|
||
replaces the manifest's kebab-case name as the env folder and env id; a device
|
||
name Windows reserves (`con`, `nul`, `com1` and the like) is refused. The
|
||
command prints one JSON document listing the written files with their sizes,
|
||
the pinned package source, the served `tool_count`, and `state` in the shape
|
||
of the serve command's stopped document. See
|
||
[agent environments](../agent-environments.md#export-a-bundle) for the folder
|
||
layout and what the smoke task checks.
|
||
|
||
`rea environment-export` prints the written files and exits `0` on success.
|
||
Input-pair refusals, an occupied destination, a missing package tarball, and
|
||
invalid labels fail before writing output. Host permission failures identify
|
||
whether reading or writing was denied and retain the affected path.
|
||
|
||
A failure during writing can leave a partial folder. Inspect it before removing
|
||
it and retrying; the next attempt refuses a non-empty destination. When one
|
||
file caused the failure, the diagnostic names that file. A folder-sync failure
|
||
can report only its cause.
|
||
|
||
If `details.partial_observation.kind` is `environment-bundle-publication`, the
|
||
bundle was already published. Its `directory` and `files` record the committed
|
||
output, even when a later identity check or cleanup failed. Inspect that bundle
|
||
and resolve the reported failure before using or replacing it; the receipt is
|
||
not an instruction to delete published output. Cleanup resources remain a
|
||
separate obligation.
|
||
|
||
## Compare an environment with its application
|
||
|
||
`rea environment-compare <manifest.json> --evidence <capture.json> --probe <probe.json> [--probe <probe.json> ...]`
|
||
compares the environment the pair serves with probe captures of the application it came from. Each probe is capture
|
||
Evidence of one call sequence recorded against the application after a reset; the environment's state is reset before
|
||
each probe, every request to the application's origin is answered as the served environment answers it, and the
|
||
answer is compared with the application's after ids are mapped and clocks and generated values are normalised. The command reads files only and
|
||
makes no network call. It prints the report and exits `0`, or prints a structured `invalid_request` error and exits `1`
|
||
for the same pair refusals as `environment-serve`, a probe that is not capture Evidence, or a browser probe captured
|
||
without response bodies, or without the request bodies its writes need. See
|
||
[agent environments](../agent-environments.md#measure-fidelity-against-the-application) for the report.
|
||
|
||
```sh
|
||
rea environment-compare manifest.json --evidence capture.json --probe probe.json --json
|
||
```
|
||
|
||
## Report version and runtime
|
||
|
||
`rea --version` prints the package version. Add an output format to get the
|
||
version with the runtime and platform context that a support request needs:
|
||
|
||
Version reports do not initialize analysis providers. Invalid global settings
|
||
or output options still report their usual errors.
|
||
|
||
```bash
|
||
rea --version --json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"name": "rea-agents",
|
||
"version": "6.7.0",
|
||
"runtime": { "id": "node", "version": "24.22.1" },
|
||
"platform": "linux",
|
||
"architecture": "x64",
|
||
"supported_runtime": {
|
||
"range": "^22.23.4 || ^24.22.1 || >=26.12.1",
|
||
"satisfied": true
|
||
}
|
||
}
|
||
```
|
||
|
||
| Field | Meaning |
|
||
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
|
||
| `name`, `version` | Published package name and version; `version` matches plain `--version`. |
|
||
| `runtime.id` | `node` or `bun`. |
|
||
| `runtime.version` | Version of that runtime. |
|
||
| `runtime.node_compatibility_version` | Bun only: the Node.js version it reports compatibility with. |
|
||
| `platform`, `architecture` | Node.js `process.platform` and `process.arch`, such as `linux` and `x64`. |
|
||
| `supported_runtime.range` | Supported Node.js range. |
|
||
| `supported_runtime.satisfied` | Whether this runtime is supported, judged as `rea doctor` judges it; Bun by its Node.js compatibility version. |
|
||
|
||
The field names are stable. The report contains no paths, environment values,
|
||
user or host names, and it starts no provider and reads no target. `--format`
|
||
selects any CLI output format, such as `--format yaml`. JSON follows the usual
|
||
rule: indented on a terminal, compact when piped or redirected. `--help` still
|
||
takes precedence. With other output controls, `--version` keeps its existing
|
||
behavior: valid controls such as `--filter-output` or `--full-output` print the
|
||
plain version, and invalid combinations report the usual output-flag error,
|
||
such as `UNSUPPORTED_OUTPUT_COMBINATION` for `--json` with `--token-limit`. Use
|
||
`rea doctor` for provider and host readiness.
|
||
|
||
## Output and exit status
|
||
|
||
Commands reject surplus positional arguments before execution, including commands
|
||
that accept no positionals. Use `rea <command> --help` for the declared argument
|
||
shape; a final variadic argument continues to accept multiple values.
|
||
`rea mcp add` accepts options only and rejects unknown options before reading or
|
||
backing up client settings or starting registration. Its `--agent` and
|
||
`--command`/`-c` options accept spaced and equals forms. Values must be nonempty; a following flag does not satisfy a spaced option's
|
||
missing value.
|
||
|
||
Registration command text is a launcher format, not a shell program. ASCII spaces
|
||
separate words; single and double quotes delimit adjacent fragments of a word.
|
||
Backslashes, tabs, variables and shell punctuation are literal data. Quoted empty
|
||
arguments are preserved, including an empty argument after the executable. An
|
||
empty executable, unfinished quote or NUL character fails before registration. For example:
|
||
|
||
```sh
|
||
rea mcp add --agent cursor --command '"/path with spaces/server" "" --mcp' --json
|
||
```
|
||
|
||
The registered executable is `/path with spaces/server`, with arguments `""` and
|
||
`--mcp`. Windows backslashes use the same literal rules after the invoking shell
|
||
has passed the option value. With no `--command`, REA uses its exact current
|
||
runtime and entrypoint arguments without converting them to text and parsing them
|
||
again. No package acquisition or server execution occurs during registration.
|
||
`--no-global` refuses any selection requiring global storage before writing files.
|
||
|
||
`rea mcp add --schema --json` returns the named input and output JSON Schemas.
|
||
Successful and partial registration reports contain the exact `command`, `args`
|
||
and a `clients` outcome list. `ok` is true only when every selected client is
|
||
configured or unchanged. Failed clients retain actionable errors; cancellation
|
||
marks remaining clients `not_started`. A failed client does not erase a successful
|
||
sibling's receipt. Existing settings and environment overrides survive refresh;
|
||
backups identify the original bytes, and identical repeats create no new backup.
|
||
Client IDs are case-insensitive for the helper-compatible catalog; documented
|
||
aliases include `droid`/`factory`, `gemini`, `grok`, `kilo`/`kilocode`, `kimi`,
|
||
`kiro`, `mastra`, `pi-agent`, `hermes-agent`, `cline-vscode`, and
|
||
`codeium`/`cascade`. `github-copilot` selects VS Code; use
|
||
`github-copilot-cli` for Copilot CLI. Amp uses `--agent amp`.
|
||
|
||
Kilo project registration follows its native configuration layers and requires a
|
||
verified Git worktree. Selected `KILO_CONFIG`, `KILO_CONFIG_DIR` and
|
||
`KILO_CONFIG_CONTENT` overrides remain authoritative. A conflicting higher-priority
|
||
source must be updated before registration can succeed; readonly layers are never
|
||
copied into the selected file. An unknown project root fails before writing and
|
||
does not fall back to global settings.
|
||
|
||
`rea mcp add --command` accepts stdio launcher text. An HTTP(S) URL in the
|
||
executable position is refused before any settings change; configure remote MCP
|
||
transport in the client's own settings. Earlier delegated registration could
|
||
interpret a URL as remote transport for some clients while storing it as an
|
||
executable for Amp. That inconsistent URL interpretation and package acquisition
|
||
are removed. Launcher arguments that happen to contain URLs remain arguments.
|
||
|
||
`rea mcp doctor --json` checks production MCP startup and reports child logs in
|
||
`diagnostics`. It drains stderr while retaining at most its first 64 KiB of raw
|
||
bytes as text, omitting a final UTF-8 code point if it crosses that byte limit.
|
||
`stderr_bytes` counts all observed bytes, including omitted output;
|
||
`stderr_truncated` indicates that output exceeded the retention limit. The same
|
||
diagnostics appear inside the report when `--full-output` is selected. Log
|
||
truncation alone does not change the diagnostic health or exit status.
|
||
|
||
The default terminal format is TOON. Use `--json` when saving results for a
|
||
JSON consumer. Valued output flags (`--format`, `--filter-output`,
|
||
`--token-limit`, `--token-offset`) accept `--flag value` or `--flag=value`; a
|
||
missing value fails with `MISSING_OUTPUT_VALUE` before the command runs.
|
||
Malformed format values and token windows fail with `INVALID_OUTPUT_VALUE` in the
|
||
selected structured format. Token limits and offsets must be nonnegative safe
|
||
integers; zero selects an empty window. These checks run before command execution. `--json` is indented on a terminal and compact when piped or
|
||
redirected, which keeps large results smaller for agents and scripts; pipe
|
||
through `jq .` for indented files. A formatting refusal exits nonzero even when
|
||
the underlying operation succeeded.
|
||
|
||
`--format md` escapes backslashes, pipes, and inline Markdown syntax in table
|
||
headers and cells so source text is displayed literally, and renders cell line
|
||
breaks as `<br>`. Underscores between letters or digits, as in `source_index`,
|
||
cannot form emphasis and stay unescaped. These are presentation changes; retained
|
||
Evidence and JSON output keep the original values. Nested objects and arrays
|
||
use JSON inside their owning Markdown cells, retaining the field names and
|
||
values instead of replacing them with an object label. Table widths are measured
|
||
iteratively, so an admitted row page is not limited by the JavaScript function
|
||
argument count.
|
||
|
||
Markdown refuses selected NUL characters and unpaired UTF-16 surrogates because
|
||
renderers or UTF-8 output would substitute them. TOON refuses selected unpaired
|
||
surrogates for the same UTF-8 reason. Use JSON or YAML to retain those values.
|
||
An authored replacement character and valid supplementary characters are not
|
||
treated as malformed.
|
||
|
||
`--format csv` and `--format tsv` export one selected row collection. Select an
|
||
exact array path with `--filter-output` and provide comma-separated direct
|
||
scalar columns with `--columns`; column order is the output column order:
|
||
|
||
For an artifact inventory request that selects the `occurrences` collection
|
||
and includes `logical_path` and `artifact_id` in its view fields:
|
||
|
||
```bash
|
||
rea inspect-analysis-view request.json --format csv \
|
||
--filter-output normalized_result.items --columns logical_path,artifact_id
|
||
```
|
||
|
||
The first line is a REA metadata record,
|
||
`# rea-delimited-v1 <JSON>`. It carries the selected path, view request, limitations and unknowns,
|
||
coverage, source coverage and completeness, command, and duration. A metadata
|
||
value of `null` means that the selected row collection did not provide that
|
||
fact; it does not mean complete coverage. The following line is the header.
|
||
CSV records use CRLF line endings; TSV records use LF. Cells containing the
|
||
delimiter, quotes, or line breaks are quoted and embedded quotes are doubled.
|
||
Values are emitted as UTF-8 without Unicode normalization. Missing and `null`
|
||
cells are empty; booleans and finite numbers use their ordinary text forms.
|
||
String cells and headers that begin with spreadsheet formula syntax are refused
|
||
with a structured error; unpaired surrogates in selected cells or headers are
|
||
also refused. JSON retains those values unchanged.
|
||
|
||
Delimited output does not flatten nested Evidence or nested field values.
|
||
It returns a structured error and a nonzero status if the filter does not
|
||
select exactly one row array, a row is not an object, or a selected cell is
|
||
nested or formula-leading. JSON remains the complete canonical output; use it
|
||
to retain fields outside the selected columns or preserve exact formula-leading
|
||
text. Token counting and token windows are not
|
||
available for CSV/TSV because slicing would corrupt records or metadata.
|
||
|
||
`--filter-output` selects fields from successful command data. Classified failures
|
||
retain their complete typed diagnostic projection even when the selector matches
|
||
a field such as `code` or `message`, or names a missing field. `--full-output`
|
||
controls whether the outer `{ok, error, meta}` envelope is included.
|
||
Selected own JSON members, including `__proto__`, remain ordinary output data.
|
||
|
||
Sibling array slices that select different fields are combined by original row
|
||
index and emitted in source order, regardless of selector order. Selecting a
|
||
whole parent row keeps that row intact and takes precedence over narrower fields
|
||
selected from the same row. For example, `rows[0,2].name,rows[1,3].version`
|
||
combines both fields for overlapping rows, while `rows[0,2],rows[1,3].version`
|
||
retains rows 0 and 1 whole.
|
||
|
||
For `cutter-command`, `--json-output` requests command-specific JSON from
|
||
Cutter when available. This is separate from `--format json`, which selects the
|
||
CLI result representation; the global `--json` flag selects that same CLI
|
||
representation.
|
||
|
||
Cutter no longer accepts command-local `--json=true` or `--json=false`.
|
||
Replace these with `--json-output=true` or `--json-output=false`, respectively.
|
||
Combine `--json-output` with bare `--json` when both Cutter command output and
|
||
the CLI result should use JSON; either argument order is accepted.
|
||
|
||
| Status | Meaning |
|
||
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `0` | The operation completed. Its result may include partial evidence, warnings or unresolved questions. |
|
||
| `1` | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available. |
|
||
| `3` | `audit-release-exposure` completed with `--fail_on` and an exposed check meets that severity. Unknown and unassessed checks do not change this status. |
|
||
| `128 + N` | Signal-derived status. An unhandled signal may have ended the process, with the shell or runtime preserving the conventional status; a command may instead have handled the signal, waited for its operation and cleanup to settle, and assigned the same status (`130` for SIGINT, `143` for SIGTERM). In the handled case, it may also have printed a structured `cancelled` result. |
|
||
|
||
`rea mcp --http` is long-running and prints no structured result. It exits
|
||
`130` on SIGINT or `143` on SIGTERM after closing the listener, the session and
|
||
its providers, and `1` when that cleanup fails.
|
||
|
||
`rea environment-serve` is also long-running: it serves until SIGINT or
|
||
SIGTERM, closes the listener, then prints one structured
|
||
`{"status":"stopped", …}` document naming the URL, environment and tool count
|
||
and exits `130` or `143` through the shared cancellation handler below.
|
||
Refusals before binding (unreadable files, non-Evidence JSON, capture Evidence
|
||
in a format other than HAR, a manifest or state whose parent is not the
|
||
supplied evidence, an unbindable port) print a structured
|
||
error and exit `1`, as does a listener that fails after binding.
|
||
If shutdown fails, the command reports `cleanup_incomplete` with the retained
|
||
server resources. It preserves a primary listener diagnostic, or a
|
||
`shutdown_observation` naming the requested shutdown and its URL, environment,
|
||
tool count and Evidence identifiers. The successful `stopped` document is
|
||
returned only after cleanup is confirmed. The same in-process server owner
|
||
retains failed stages for retry; the CLI exposes no separate retry command.
|
||
`rea environment-build` is one-shot too: it prints its report and exits `0`,
|
||
or prints the refusing stage's structured error and exits `1`, writing nothing
|
||
when the refusal comes before the bundle is written. SIGINT cancels it with a
|
||
`cancelled` error; a cancellation before the bundle stage writes nothing.
|
||
A `cancelled` result does not by itself determine the exit status. Commands
|
||
that handle SIGINT or SIGTERM assign `130` or `143` after their operation and
|
||
cleanup settle; their structured result can be printed before that status is
|
||
assigned. Read the process status and typed result separately.
|
||
|
||
Commands with `--evidence_output` save the complete Evidence bundle before
|
||
delivering the selected view. For committed-file receipts, retained partial
|
||
Evidence and missing source records, see
|
||
[Evidence publication and source recovery](../reference/mcp-contracts.md#evidence-publication-and-source-recovery).
|
||
Other outputs have their own receipt shapes; for example,
|
||
[environment export](#export-an-environment-bundle) reports a published directory.
|
||
|
||
A failure that carries partial Evidence in `details.partial_observation`, such
|
||
as `provider_timeout` or `resource_constraint`, publishes that partial Evidence
|
||
to `--evidence_output` under the same new-file and atomic rules, then keeps its
|
||
error code, message and remediation when cleanup is confirmed. With `--detail summary`,
|
||
`details.partial_observation` holds the summary view of the partial Evidence
|
||
instead of the complete record, and `details.diagnostics.evidence_bundle`
|
||
reports the written path and byte count. Linked source records must all be
|
||
available before publication; missing sources leave the destination unchanged
|
||
and are reported in `details.source_closure`. A provider cleanup failure can
|
||
still publish its captured Evidence without clearing the cleanup error or its
|
||
resource ownership. If publication is refused before commit, for example because
|
||
the file already exists, the complete partial Evidence stays inline and `details.diagnostics.evidence_bundle_error` gives the
|
||
refusal's code, message and a limitation. A refusal after commit keeps the
|
||
receipt in `details.diagnostics.evidence_bundle` and the delivered view: when
|
||
staging cleanup stays incomplete, the code becomes `cleanup_incomplete`, the
|
||
original failure is retained in `details.execution_failure`, and `details` also carries `published`,
|
||
`published_path`, `bytes`, `cleanup: "incomplete"` and `resources`, as for a
|
||
successful run, and a later cancellation reports `cancelled` in
|
||
`evidence_bundle_error` with the signal's exit status. Without
|
||
`--evidence_output`, and for cancellation before publication or raw provider
|
||
observations, the failure output is unchanged.
|
||
|
||
When the reader of piped output closes early, as `rea ... | head` does, the
|
||
CLI stops writing, prints no error and exits `141` (`128 + 13`, the status of a
|
||
SIGPIPE-terminated writer). The operation itself may have completed; only its
|
||
output was declined.
|
||
|
||
`inspect-artifact` also returns a structured cancelled result. Its logging
|
||
wrapper sits outside the cancellation handler and replaces the signal-derived
|
||
status with the analysis failure status, so it exits `1`. Setup has its own contract: cancellation exits `0`. Treat the
|
||
structured result and process status as separate signals when scripting
|
||
cancellation.
|
||
|
||
`setup --dry-run` returns `planned` and exits `0`. For `setup` and
|
||
`environment-build`, explicit `--dry-run=true` and `--dry-run=false` are
|
||
accepted; empty or other values fail with `PARSE_ERROR` before any changes.
|
||
Every supplied value is checked even when a later occurrence overrides it.
|
||
A cancelled setup also exits
|
||
`0`. Setup returns `1` for `needs_confirmation` or `needs_human`.
|
||
`doctor` returns `1` when required checks in its selected readiness scope fail;
|
||
unavailable optional providers remain informational for unrelated tasks.
|
||
|
||
Enable `pipefail` in a supporting shell so a downstream formatter preserves
|
||
REA's failure status:
|
||
|
||
```bash
|
||
set -o pipefail
|
||
rea inspect-artifact ./app.asar --json | jq . > inspection.json
|
||
```
|
||
|
||
`--token-count` reports a tokenx estimate for the selected emitted document,
|
||
including a requested full-output envelope and metadata. JSON uses the same
|
||
terminal indentation or compact piped representation as normal output; JSONL
|
||
uses its emitted line representation. The final newline is included (tokenx
|
||
assigns whitespace no tokens). This is an estimate, not a model tokenizer count.
|
||
Counting retains the existing bounded formatted-string allocation after capacity
|
||
admission; omit the flag to stream large JSON documents without materializing
|
||
the complete formatted text. Exhausted token windows display an empty range at
|
||
the total token count and have no next offset.
|
||
|
||
### `inspect-devicetree`
|
||
|
||
Inspect an explicit local FDT v16/v17 blob without execution or an external tool.
|
||
Returns header, reservations, node/property tree, derived standard values and
|
||
selected phandle references. See [devicetree inspection](../devicetree.md) for
|
||
limits and retained-view pagination.
|
||
|
||
```bash
|
||
rea inspect-devicetree /artifacts/board.dtb --json
|
||
rea inspect-devicetree /artifacts/board.dtb --detail summary --evidence_output /artifacts/board-evidence.json --json
|
||
```
|
||
|
||
### PE TLS and load configuration
|
||
|
||
```sh
|
||
rea inspect-pe-load-config /absolute/path/to/application.exe --json
|
||
```
|
||
|
||
Reports TLS callbacks and size-covered load-config fields without execution.
|
||
Use `--max-callbacks` and `--max-file-bytes` to set read budgets. See
|
||
[PE TLS and load configuration](../pe-load-config.md).
|
||
|
||
### Binary hardening
|
||
|
||
```sh
|
||
rea inspect-binary-hardening /absolute/path/to/program --json
|
||
```
|
||
|
||
Reports ELF, PE, and Mach-O hardening rows without execution. A missing import
|
||
is `unknown`, not `disabled`. Use `--max-file-bytes` to set the read budget. See
|
||
[binary hardening](../binary-hardening.md).
|
||
|
||
Bun standalone executables use the existing `inspect-artifact` and
|
||
`extract-artifact` commands to inventory and materialize embedded source,
|
||
sourcemaps and bytecode without running the executable. See
|
||
[Bun standalone executables](../bun-standalone.md) for layout coverage and limits.
|
||
|
||
### Release exposure
|
||
|
||
```sh
|
||
rea audit-release-exposure /absolute/path/to/MyApp.app --json
|
||
rea audit-release-exposure ./dist/MyApp.app --fail_on high --json
|
||
```
|
||
|
||
Reports what static analysis of a shipped `.app`, install directory, ASAR, or
|
||
executable recovers. `--fail_on high|medium|low` exits `3` when a completed
|
||
audit has an exposed check at that severity. Unknown and unassessed checks stay
|
||
in the report and do not change the exit status. See
|
||
[Release exposure](../release-exposure.md).
|
||
Deno compile executables use the same commands to inventory and materialize the
|
||
embedded virtual filesystem, remote modules, and recorded options. Inventory retains
|
||
embedded environment-file values and certificate bytes in local Evidence with their
|
||
counts and byte lengths, and extraction does not write them as files. The npm snapshot
|
||
length is reported and not decoded, and the executable is not run. See
|
||
[Deno compile executables](../deno-standalone.md).
|