morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #3893] [Bug] Documented --follow-debug-links false example enables DWARF debug-link following #1513

New issue

Closed

opened 2026-10-16 21:06:26 +00:00 by bsakaguchi · 2 comments

bsakaguchi commented

2026-10-16 21:06:26 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 15, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3893

Before submitting

I searched the open and closed issues for a related report.
I removed credentials, tokens, private paths, and sensitive target data.

Area

Documentation

Observed behavior

The objdump DWARF example in docs/reverse-engineering-tools.md passes --follow-debug-links false, which reads as explicitly disabling debug-link following. The CLI parses --follow-debug-links as a Boolean flag, so the spaced false form turns following on: the Evidence records follow_debug_links: true and the objdump arguments contain -WK. Users who copy the example get the opposite of what it says.

The documented --follow-debug-links false form records follow_debug_links: true and passes -WK. Both --no-follow-debug-links and --follow-debug-links=false record false and pass -WN. Omitting the option also records false.

Reproduction

Run the documented form against any local binary and select the recorded parameters.

rea inspect-with-objdump /bin/ls dwarf --follow-debug-links false --filter-output parameters.follow_debug_links,parameters.command_arguments --json

Run the two corrective forms as controls.

rea inspect-with-objdump /bin/ls dwarf --no-follow-debug-links --filter-output parameters.follow_debug_links,parameters.command_arguments --json
rea inspect-with-objdump /bin/ls dwarf --follow-debug-links=false --filter-output parameters.follow_debug_links,parameters.command_arguments --json

Expected behavior

Following the documented example should keep debug-link following disabled: follow_debug_links: false and -WN in the objdump arguments. The documentation should show a form that produces that result, such as --no-follow-debug-links or --follow-debug-links=false, or omit the option to rely on its false default.

Impact and scope

Users copying the documented example request local debug-link following instead of disabling it; with GNU objdump -WK can add external debug-file content whose identity is not bound to the artifact Evidence.

Workaround: available. --no-follow-debug-links, --follow-debug-links=false, or omitting the option all record false and select -WN, as observed.

Reporter's impact estimate: P2 (supported).

REA version

6.5.0, built from source at main commit 034342ba28 (latest npm release is 6.5.0)

Runtime and platform

Node.js v26.10.0; macOS 27.0.1 arm64; The host objdump (/usr/bin/objdump, Apple LLVM) rejects -W, so this establishes the parsed option value and selected subprocess arguments, not a successful GNU DWARF run or an observed external debug-file read.

Target and artifact context

Mach-O executable (/bin/ls) with objdump dwarf operation

Interface

CLI

Earliest failure stage

Request parsing or validation

Relevant output or evidence

Expected source: docs/reverse-engineering-tools.md:19 (DWARF does not follow local debug links by default; enabling passes -WK; external debug-file identities are not bound to Evidence) and the example at docs/reverse-engineering-tools.md:23
Failure source: public CLI output for the documented example; static cause at src/cli/reverseEngineeringCommands.ts:126 and :141 with src/objdump/ObjdumpCommand.ts:19
Evidence provenance: observed
Local verification: reproduced
Reproduction completeness: complete

Documented form:

{"parameters":{"follow_debug_links":true,"command_arguments":["-W","-WK","/bin/ls"]}}

--no-follow-debug-links and --follow-debug-links=false controls, identical output:

{"parameters":{"follow_debug_links":false,"command_arguments":["-W","-WN","/bin/ls"]}}

Source-derived cause: src/cli/reverseEngineeringCommands.ts:126 registers followDebugLinks as a Boolean option with a false default and line 141 passes it directly as follow_debug_links; src/objdump/ObjdumpCommand.ts:19 selects -WK when true and -WN when false. A bare Boolean flag consumes no value, so the following false token does not set it.

Typed outcome or recovery expected

The documented example should produce follow_debug_links: false with -WN, or the CLI should reject the stray 'false' value instead of enabling the flag.

Restoration check:

Running the exact documented DWARF example from docs/reverse-engineering-tools.md on the tested build records follow_debug_links: true with -WK; after the fix, the documented example should record follow_debug_links: false with -WN, whether the fix changes the example or the option parsing. The --no-follow-debug-links control must keep recording false with -WN.

Analysis or suspected cause

Source-derived: src/cli/reverseEngineeringCommands.ts:126 declares followDebugLinks as a Boolean option, so the bare flag sets true and the next 'false' token is not its value; src/objdump/ObjdumpCommand.ts:19 then selects -WK.

Additional context

The same paragraph at docs/reverse-engineering-tools.md:19 also states "The CLI option is --follow-debug-links true"; that spaced true form was not tested. Open #3656 discusses objdump provider scope and authority, not this example.

This report came from AI-assisted source review with local reproduction where stated above; the evidence labels distinguish observed runs from source-only reasoning.

Originally created by @coygeek on GitHub (Oct 15, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3893 ### Before submitting - [x] I searched the open and closed issues for a related report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Area Documentation ### Observed behavior The objdump DWARF example in docs/reverse-engineering-tools.md passes `--follow-debug-links false`, which reads as explicitly disabling debug-link following. The CLI parses `--follow-debug-links` as a Boolean flag, so the spaced `false` form turns following on: the Evidence records `follow_debug_links: true` and the objdump arguments contain `-WK`. Users who copy the example get the opposite of what it says. The documented `--follow-debug-links false` form records `follow_debug_links: true` and passes `-WK`. Both `--no-follow-debug-links` and `--follow-debug-links=false` record `false` and pass `-WN`. Omitting the option also records `false`. ### Reproduction 1. Run the documented form against any local binary and select the recorded parameters. ```sh rea inspect-with-objdump /bin/ls dwarf --follow-debug-links false --filter-output parameters.follow_debug_links,parameters.command_arguments --json ``` 2. Run the two corrective forms as controls. ```sh rea inspect-with-objdump /bin/ls dwarf --no-follow-debug-links --filter-output parameters.follow_debug_links,parameters.command_arguments --json rea inspect-with-objdump /bin/ls dwarf --follow-debug-links=false --filter-output parameters.follow_debug_links,parameters.command_arguments --json ``` ### Expected behavior Following the documented example should keep debug-link following disabled: `follow_debug_links: false` and `-WN` in the objdump arguments. The documentation should show a form that produces that result, such as `--no-follow-debug-links` or `--follow-debug-links=false`, or omit the option to rely on its false default. ### Impact and scope Users copying the documented example request local debug-link following instead of disabling it; with GNU objdump `-WK` can add external debug-file content whose identity is not bound to the artifact Evidence. Workaround: available. `--no-follow-debug-links`, `--follow-debug-links=false`, or omitting the option all record `false` and select `-WN`, as observed. Reporter's impact estimate: P2 (supported). ### REA version 6.5.0, built from source at main commit 034342ba28c8e56c3746be92b78aa7299afa02bd (latest npm release is 6.5.0) ### Runtime and platform Node.js v26.10.0; macOS 27.0.1 arm64; The host objdump (`/usr/bin/objdump`, Apple LLVM) rejects `-W`, so this establishes the parsed option value and selected subprocess arguments, not a successful GNU DWARF run or an observed external debug-file read. ### Target and artifact context Mach-O executable (/bin/ls) with objdump dwarf operation ### Interface CLI ### Earliest failure stage Request parsing or validation ### Relevant output or evidence - Expected source: docs/reverse-engineering-tools.md:19 (DWARF does not follow local debug links by default; enabling passes `-WK`; external debug-file identities are not bound to Evidence) and the example at docs/reverse-engineering-tools.md:23 - Failure source: public CLI output for the documented example; static cause at src/cli/reverseEngineeringCommands.ts:126 and :141 with src/objdump/ObjdumpCommand.ts:19 - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete Documented form: ```json {"parameters":{"follow_debug_links":true,"command_arguments":["-W","-WK","/bin/ls"]}} ``` `--no-follow-debug-links` and `--follow-debug-links=false` controls, identical output: ```json {"parameters":{"follow_debug_links":false,"command_arguments":["-W","-WN","/bin/ls"]}} ``` Source-derived cause: src/cli/reverseEngineeringCommands.ts:126 registers `followDebugLinks` as a Boolean option with a false default and line 141 passes it directly as `follow_debug_links`; src/objdump/ObjdumpCommand.ts:19 selects `-WK` when true and `-WN` when false. A bare Boolean flag consumes no value, so the following `false` token does not set it. ### Typed outcome or recovery expected The documented example should produce follow_debug_links: false with -WN, or the CLI should reject the stray 'false' value instead of enabling the flag. Restoration check: Running the exact documented DWARF example from docs/reverse-engineering-tools.md on the tested build records `follow_debug_links: true` with `-WK`; after the fix, the documented example should record `follow_debug_links: false` with `-WN`, whether the fix changes the example or the option parsing. The `--no-follow-debug-links` control must keep recording `false` with `-WN`. ### Analysis or suspected cause Source-derived: src/cli/reverseEngineeringCommands.ts:126 declares followDebugLinks as a Boolean option, so the bare flag sets true and the next 'false' token is not its value; src/objdump/ObjdumpCommand.ts:19 then selects -WK. ### Additional context The same paragraph at docs/reverse-engineering-tools.md:19 also states "The CLI option is `--follow-debug-links true`"; that spaced `true` form was not tested. Open #3656 discusses objdump provider scope and authority, not this example. This report came from AI-assisted source review with local reproduction where stated above; the evidence labels distinguish observed runs from source-only reasoning.

bsakaguchi closed this issue

2026-10-16 21:06:26 +00:00

bsakaguchi commented

2026-10-16 21:06:28 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 15, 2026):

Good catch — the docs example is actively misleading because --follow-debug-links false reads naturally as disabling, yet a bare Boolean flag treats the trailing token as a positional arg and actually enables following (with -WK passed to objdump). That flips the user's intent into the opposite behavior. Fixing the doc to show --follow-debug-links=false or --no-follow-debug-links (or omitting it since the default is false) is the right call; worth also grepping the other examples in the same doc for the same spaced-false pattern, since the parser behavior isn't going to change without breaking the flag syntax.

@XinwangTao commented on GitHub (Oct 15, 2026): Good catch — the docs example is actively misleading because `--follow-debug-links false` reads naturally as disabling, yet a bare Boolean flag treats the trailing token as a positional arg and actually enables following (with -WK passed to objdump). That flips the user's intent into the opposite behavior. Fixing the doc to show `--follow-debug-links=false` or `--no-follow-debug-links` (or omitting it since the default is false) is the right call; worth also grepping the other examples in the same doc for the same spaced-false pattern, since the parser behavior isn't going to change without breaking the flag syntax.

bsakaguchi commented

2026-10-16 21:06:28 +00:00

Author

Owner

@yankikucuk commented on GitHub (Oct 15, 2026):

Working on this. Reproduced on macOS: the documented --follow-debug-links false records follow_debug_links: true with -WK; --no-follow-debug-links, --follow-debug-links=false and omitting the option record false with -WN. The guide now names the bare flag, points to the explicit negative spellings, explains why the spaced form enables following, and shows the default and enabling examples. No other spaced-boolean examples exist in the docs (checked --<flag> true|false across docs, README and the shipped skill). The CLI silently accepting the stray trailing token is left as is here. Draft PR follows shortly.

@yankikucuk commented on GitHub (Oct 15, 2026): Working on this. Reproduced on macOS: the documented `--follow-debug-links false` records `follow_debug_links: true` with `-WK`; `--no-follow-debug-links`, `--follow-debug-links=false` and omitting the option record `false` with `-WN`. The guide now names the bare flag, points to the explicit negative spellings, explains why the spaced form enables following, and shows the default and enabling examples. No other spaced-boolean examples exist in the docs (checked `--<flag> true|false` across docs, README and the shipped skill). The CLI silently accepting the stray trailing token is left as is here. Draft PR follows shortly.

bsakaguchi referenced this issue

2026-10-17 21:11:59 +00:00

[PR #1513] [MERGED] fix: bind identity and coverage to the producing rule #2933

bsakaguchi referenced this issue

2026-10-17 21:12:11 +00:00

[PR #1535] [MERGED] fix(reference): join internal symlink targets with the inventory NFC normalizer #2952

bsakaguchi referenced this issue

2026-10-17 21:12:21 +00:00

[PR #1553] [MERGED] fix(artifacts): take nested container families from bytes #2967

bsakaguchi referenced this issue

2026-10-17 21:12:45 +00:00

[PR #1604] [MERGED] fix(browser): fold loopback spellings into one attach admission key #3000