Login Register
vee1e

vee1e / f5d28b8b9f2e414907191dcd0eb39508

Last active 4 days ago

Like 0

Lakshit Verma revised this gist 4 weeks ago · 237198d

1 file changed, 3 insertions, 2 deletions

migration-doc.md
@@ -257,6 +257,7 @@ The goals are:
257 257 >
258 258 > - (Moritz Raabe) TBD.
259 259 >
260 +
260 261 > [!NOTE]
261 262 > The default view mode is not final. Confirm before the major release.
262 263
@@ -290,7 +291,7 @@ In flat and grouped views, a comma-separated list controls column visibility:
290 291 >
291 292 > - (Willi Ballenthin) Do agents really do a better job with JSON? Or is this more to support programmatic use of the output?
292 293 > - (Moritz Raabe) TBD, but yes. Refining this here.
293 - >
294 +
294 295 > [!NOTE]
295 296 > The JSON output direction is still under review.
296 297
@@ -345,7 +346,7 @@ In flat and grouped views, a comma-separated list controls column visibility:
345 346 > **Review comment on `--no-layout`:**
346 347 >
347 348 > - (Moritz Raabe) Do this via `--view` instead.
348 - >
349 +
349 350 > [!NOTE]
350 351 > The final removal of `--no-layout` is not confirmed.
351 352

Lakshit Verma revised this gist 4 weeks ago · 0cafaa4

1 file changed, 33 insertions, 10 deletions

migration-doc.md
@@ -12,6 +12,7 @@
12 12 - https://github.com/mandiant/flare-floss/issues/1295
13 13 - https://github.com/mandiant/flare-floss/issues/943
14 14 - https://github.com/mandiant/flare-floss/issues/1336
15 + - https://github.com/mandiant/flare-floss/issues/1350
15 16
16 17 ## Purpose
17 18
@@ -75,7 +76,9 @@ Decide whether a plain, table-free mode is needed for scripts.
75 76
76 77 Where should decoded strings appear?
77 78
78 - Use offsets to place them.
79 + Possible feature: use offsets to place them.
80 +
81 + This is not 100% guaranteed. It may change or not ship.
79 82
80 83 Example structure:
81 84
@@ -107,13 +110,13 @@ Base other options on what a human does in the interactive web view.
107 110
108 111 **Status:** Complete.
109 112
110 - **Action:** Design a metrics and performance plan in a later iteration. Do not block this PR.
113 + **Action:** Address this later, after the FLOSS QS merge is complete but before the auto DB build starts.
111 114
112 115 ### 2.2 Load flag ignores layout flags
113 116
114 117 **Discussion:** `floss --load file.json --no-layout` still renders the layout view. The load function does not clear `results.layout` or apply `enable_layout`.
115 118
116 - **Decision:** Noted as a TODO and issue #1348.
119 + **Decision:** Noted as a TODO and issue #1348. We are removing `--no-layout` entirely. Whether to remove it completely is a matter of debate.
117 120
118 121 **Status:** Open. TODOs at `floss/results.py:350` and `floss/render/default.py:361`.
119 122
@@ -147,7 +150,7 @@ Base other options on what a human does in the interactive web view.
147 150
148 151 **Status:** Complete.
149 152
150 - **Action:** Optional later improvement: show meta above the layout tree. Or show meta under `--verbose`, without `--no-layout`.
153 + **Action:** Mandatory for this PR: show meta above the layout tree. Or show meta under `--verbose`, without `--no-layout`.
151 154
152 155 ### 2.6 Full-buffer read for static extraction
153 156
@@ -177,6 +180,7 @@ Fix these paths.
177 180 - [QS: move db contents to tags folder](https://github.com/mandiant/flare-floss/issues/1336) — fix the stale `floss/qs/db/data` paths in two scripts.
178 181 - [qs: add option to disable printing of strings with given tag](https://github.com/mandiant/flare-floss/issues/795) — decide the `--filter` semantics and scope.
179 182 - [support filters like "many special characters" or "many repeats"](https://github.com/mandiant/flare-floss/issues/725) — decide the `--filter` semantics and scope.
183 + - [QS/FLOSS: Add completion scripts](https://github.com/mandiant/flare-floss/issues/1350) — add zsh, bash, and fish completion scripts for FLOSS arguments so a tab press shows completions without running `--help`.
180 184 - Decide whether to add a `--plain` output mode.
181 185
182 186 ## Part 3: CLI specification and design (layout and tag aware)
@@ -214,7 +218,7 @@ The goals are:
214 218
215 219 #### 3.3.1 Removed redundant aliases
216 220
217 - - Removed `--exclude-aliases`. Exclusions strictly use `--no-` (`--no-type`, `--no-section`, `--no-structure`, `--no-tag`).
221 + - Removed `--exclude-aliases`. Exclusions strictly use `--no <type>` for less bloat.
218 222 - Removed `--noise-reduction` alias. Noise suppression strictly uses `--clean`.
219 223 - Removed boolean column toggles (`--show-encoding`, `--show-offset`, `--show-tags`). A single `--columns` option replaces them.
220 224
@@ -229,13 +233,17 @@ The goals are:
229 233
230 234 - Multi-value matching: Passing multiple values to a flag uses OR logic. Strings matching any of the specified values are included or excluded.
231 235 - `--interesting`: Automatically excludes noisy tags (#common, #duplicate, #code, #reloc, #code-junk).
232 - - `--no-tag-engine`: Disables the tag evaluation engine entirely.
236 + - `--no-tag <tag...>`: Suppress strings matching specified tags. This is the only way to disable tag evaluation.
233 237
234 - > **Review comments on `--no-tag-engine`:**
238 + > **Final decision on `--no-tag-engine`:**
239 + >
240 + > Rejected. The review comments show the trade-off:
235 241 >
236 242 > - (Willi Ballenthin) Is this necessary?
237 243 > - (Moritz Raabe) Maybe? We could do it with `--tag none` or similar.
238 244 > - (Lakshit Verma) Yes. `--tag none` would avoid bloating the argument list and is easy to explain.
245 + >
246 + > Final decision: keep `--no tag` only.
239 247
240 248 ### 3.4 Output rendering and terminal views
241 249
@@ -248,6 +256,9 @@ The goals are:
248 256 > **Review comment on `--view`:**
249 257 >
250 258 > - (Moritz Raabe) TBD.
259 + >
260 + > [!NOTE]
261 + > The default view mode is not final. Confirm before the major release.
251 262
252 263 #### 3.4.2 In-tree search and filtering
253 264
@@ -269,13 +280,19 @@ In flat and grouped views, a comma-separated list controls column visibility:
269 280 > - (Willi Ballenthin) Consider the TOON format for token efficiency: https://github.com/toon-format/toon. But maybe translating to a different format is the responsibility of the caller.
270 281 > - (Moritz Raabe) Good reference. We are going for something like this with the text output, so consider leveraging it directly.
271 282
272 - - `--summary`: Summary containing sample metadata, section counts, tag histograms, and strings matching high-value tags (#capa, winapi, crypto). TBD: also support with `-j`? Ideally base everything on JSON output for programmatic access, then render from there for humans and agents.
283 + - `--summary`: Summary containing sample metadata, section counts, tag histograms, and strings matching high-value tags (#capa, winapi, crypto). Ideally base everything on JSON output for programmatic access, then render from there for humans and agents.
284 +
285 + > [!NOTE]
286 + > TBD: should `--summary` also work with `-j`?
273 287 - Structured JSON errors: When any JSON output mode is active, fatal CLI or parsing errors emit a structured JSON object to STDERR (for example `{"error": "...", "code": ...}`) rather than unstructured text.
274 288
275 289 > **Review comments on JSON output:**
276 290 >
277 291 > - (Willi Ballenthin) Do agents really do a better job with JSON? Or is this more to support programmatic use of the output?
278 292 > - (Moritz Raabe) TBD, but yes. Refining this here.
293 + >
294 + > [!NOTE]
295 + > The JSON output direction is still under review.
279 296
280 297 ### 3.6 Non-static string processing (TODO roadmap)
281 298
@@ -303,6 +320,9 @@ In flat and grouped views, a comma-separated list controls column visibility:
303 320 - `--help`: Display advanced options and exit.
304 321 - `--version`: Display program version and exit.
305 322
323 + > [!NOTE]
324 + > Add zsh, bash, and fish completion scripts for the FLOSS arguments. Tracked in https://github.com/mandiant/flare-floss/issues/1350. A tab press then shows completions without running `--help`.
325 +
306 326 #### 3.7.3 Analysis and extraction options
307 327
308 328 - `-t <type...>`, `--string-type <type...>`: Select string types to extract (static, stack, tight, decoded, language, all; default: all).
@@ -320,11 +340,14 @@ In flat and grouped views, a comma-separated list controls column visibility:
320 340 - `--no-section <name...>`: Exclude strings in specified binary sections.
321 341 - `--structure <name...>`: Restrict static strings to specified binary structures.
322 342 - `--no-structure <name...>`: Exclude strings in specified structures.
323 - - `--no-layout`: Disable binary layout reconstruction engine.
343 + - `--no-layout`: Disable binary layout reconstruction engine. Being removed entirely; whether to remove it completely is a matter of debate.
324 344
325 345 > **Review comment on `--no-layout`:**
326 346 >
327 347 > - (Moritz Raabe) Do this via `--view` instead.
348 + >
349 + > [!NOTE]
350 + > The final removal of `--no-layout` is not confirmed.
328 351
329 352 #### 3.7.5 Tagging, searching, and noise filtering options
330 353
@@ -390,7 +413,7 @@ The CLI specification above refines the earlier design options.
390 413 Apply these decisions:
391 414
392 415 - Use `--string-type` and `--no-string-type` for string kinds. This replaces the current `--no` and `--only`.
393 - - Use `--no-layout` only as a temporary flag. The final design uses `--view flat` instead.
416 + - Use `--no-layout` only as a temporary flag. The final design uses `--view flat` instead. Removing `--no-layout` entirely is under debate.
394 417 - Use `--tag` and `--no-tag` for filter by tag. This replaces the proposed `--filter`.
395 418 - Use `--view` for display modes. Do not add a separate `--plain` mode.
396 419 - Remove `--large-file`. Process any file.

Lakshit Verma revised this gist 4 weeks ago · abd2d92

1 file changed, 405 insertions

migration-doc.md (file created)

Diff is too large to be shown