Skip to content

v0.0.7

Choose a tag to compare

@nightshift-labs-ai nightshift-labs-ai released this 18 Nov 13:39
· 21 commits to main since this release

In short

  • Annotate ends with a summary window (menu only): N of M static-key NOP sites can jump to code nothing else in this database reaches, one line per table, and buttons Static-key sites, BUG/WARN sites and Close that open the lists. Tested only with fake ida_* modules; not yet run in IDA.
  • Pseudocode says when code is probably hidden: a static-key site's comment adds that nothing else in the database jumps or falls through to the code the site does not run here, so the pseudocode probably does not show it. The flow check is tested; what Hex-Rays then shows is not checked in real IDA, hence "probably".
  • Go to oops/WARN line can be tried on any kernel: python3 -m kflow <kernel> --oops-example prints a WARNING: line built from the file's own __bug_table, the IDA dialog offers the same kind of line the first time, and --oops also takes the line itself.
  • List static-key sites has a Block column (bytes / insns of the out-of-line block at each target), and the README has a "Without kflow / with kflow" table right after Status and a quick path on dm-mod.ko from the kflow-try-module.zip asset.
  • Requires IDA 9.1 or later (was 9.0): the IDA API names are checked only against the IDAPython stubs of 9.1 to 9.5.

Details

  • Supported IDA versions: 9.1 or later (ida-plugin.json idaVersions >=9.1; README, docs and the headless runner's messages say the same). The IDA API names are checked against the IDA 9.1 to 9.5 stubs only, so 9.0 was never checked; same rule as the sister plugin btf2ida. hcli no longer offers this version to IDA 9.0.
  • README front door: the opening leads with static keys (96% of the 8,349 NOP sites on the MemLens demo kernel, now explained at first mention as a Debian 13 6.12 x86_64 kernel exported from a memory image; re-measured with tools/reach.py: 8,037 of 8,349, 96.3%), then file:line without DWARF, then the oops report; the before/after and pseudocode blocks put each kflow comment under its instruction, wrapped (labelled so), so no code line is over 110 characters (before: 121, 176 and 230); the table's static-key row says what is lost without the reference, the WARN/BUG and oops cells get a verb and units (586 source lines map to 2+ traps, 506 of them in 2+ named functions, re-counted with python3 -m kflow's decoder), and a new Pseudocode row; the Features list is shorter (README 1,775 words before this release's additions, 1,906 now, wc -w). tests/test_core.py fails on a README code line over 110 characters; on a kernel with the README's addresses (the demo kernel), tests/test_entry_stub.py checks that each wrapped comment, unwrapped, is the code's own text. docs/VERIFICATION.md lists the try module dm-mod.ko (74 / 22 / 2 sites; six modules now).
  • docs/USAGE.md: "Try a real module" now starts with kflow-try-module.zip (Debian 13 x86_64 dm-mod.ko, as in the README): the two commands (python3 -m kflow dm-mod.ko: 74 / 22 / 2 sites; --oops "$(... --oops-example)": exact, rc 0, re-run) and the same three what-you-should-see steps; the arm64 ext4.ko download follows as the second option, its command lines wrapped to at most 110 characters (before: 122, 126 and 135).
  • Go to oops/WARN line, first try: when the dialog starts with the example WARNING: line built from the database, its prompt says so (kflow: below is an example built from this database's __bug_table; replace it with your kernel log ...); with an empty dialog or after a paste it shows the usual prompt (fake-IDA test). Command line: --oops also takes the line itself, so python3 -m kflow kernel.elf --oops "$(python3 -m kflow kernel.elf --oops-example)" gives exact, rc 0, on Debian 13 dm-mod.ko and the MemLens demo kernel (before: [Errno 2] No such file or directory, rc 2). An argument that is no existing file and has a newline, WARNING:, BUG, RIP:, pc :, +0x or :<digit> is read as the log, with a note on stderr, unless it reads like a path (no whitespace, and it starts with /, ~ or . or ends in .log/.txt: a missing /tmp/BUG-report.txt gave no match, rc 1, now no such file, rc 2; a bare func+0x674/0x9d0 is still read as the log); any other missing file still gives rc 2, now with a message naming the log file, - (stdin) and the quoted line. - reads stdin as before. README step 3 shows the round trip.
  • README quick path (kflow-try-module.zip): the command-line counts and Annotate are separate sentences, and three steps say what to look at after Annotate: the window's headline (22 of 22 in the fake-IDA test, which has no other references; real IDA may show fewer), F5 in dm_submit_bio (4 zoned_enabled sites and the block_split tracepoint; in the fake, all 5 comments end with the hidden-path sentence), and Go to oops/WARN line's first text WARNING: CPU: 0 PID: 1 at drivers/md/dm-zone.c:35 dm_blk_do_report_zones.isra.0+0x91/0xc0 [dm_mod], which lands on that ud2. Labelled as fake-IDA text; kflow has not yet run in real IDA. On dm-mod.ko, tests/test_entry_stub.py checks every number and name of that paragraph against its run and the command line, and tests/test_oops.py checks the quoted line against --oops-example.
  • Annotate's summary window (menu only) starts with the line kflow: Annotate finished (a plain line: the TITLE prefix that IDAPython passes to ask_yn is not documented for ask_buttons), and reads as a result: the headline N of M static-key NOP sites can jump to code nothing else in this database reaches: kflow's reference is the only one that leads there (with the decompiler: ; the site's pseudocode comment says so; when N is 0: ...reaches: every target has another way in.), one line per table in the README's nouns (74 BUG/WARN sites (37 WARN): a comment with the source file:line, 22 static-key sites: ..., 2 exception-table fixups: ... on Debian 13 dm-mod.ko), the sites left without a reference when IDA has no instruction there, the decompile check's line, and a next step: with the decompiler, press F5 in <function> (<n> hidden-path static-key sites) for the function with the most such NOP sites, and Go to oops/WARN line starts with a WARNING line built from this database when it can build one and nothing was pasted yet (if building it fails, the window shows without that line). The raw counts line (comments: ..., jump references added: ...) is now only in the Output window and in tools/kflow_headless.py's output, unchanged. Fake-IDA test on dm-mod.ko: 22 of 22, press F5 in dm_submit_bio (5 hidden-path static-key sites); tested only with fake ida_* modules; not yet run in IDA.
  • Annotate's summary window is an ida_kernwin.ask_buttons window with buttons Static-key sites and BUG/WARN sites (they open the two lists) and Close (the default; Esc). In its headline, M counts the static-key sites that are NOPs here and N those whose target has no other way in (the rule of the pseudocode sentence). No window when nothing was annotated; if the window fails, one line in the Output window says so. tools/kflow_headless.py prints text as before. Tested only with fake ida_* modules (on the MemLens demo kernel the fake gives 8349 of 8349 in one test and 8348 of 8349 in another, each the count that test works out itself); not yet run in IDA. tests/check_ida_api.py also checks ask_buttons (argument order, return values): 232 checks.
  • README: a "Without kflow / with kflow" table right after Status, static keys first. It says plainly what IDA and a debug build already give (IDA's Jump dialog takes func+off; a DWARF vmlinux has file:line; ordinary flow already reaches the fixups of 51% of the exception-table sites) and where kflow adds something (static keys, kernels without DWARF, WARN vs BUG, whole-report parsing and file:line to every inlined copy), credits linux_und.py and the SDK example ana_emu_out.py, and dates the "no public __jump_table decoder found" search. Every number re-measured with tools/reach.py and python3 -m kflow on the MemLens demo kernel (static keys also on Ubuntu 6.8).
  • Go to oops/WARN line: the dialog's pre-filled WARNING: line no longer names a function at an offset past its printed size. On GKI 6.1 arm64 two static functions are both called gic_handle_irq; IDA's name lookup gives the first one's start for both, so the dialog offered gic_handle_irq+0x190/0xf4, which pasted back was not an exact match. oops.example_line now skips a site whose offset is not below the printed size (the CLI's --oops-example already skipped such names; its output is unchanged).
  • python3 -m kflow <kernel> --oops-example prints a WARNING: CPU: 0 PID: 1 at file:line func+0xoff/0xsize line (with [module] for a module) built from the file's own __bug_table: the first WARN site with a file:line in a uniquely named function, so Go to oops/WARN line and --oops can be tried on any kernel, not only on the demo. In IDA, Go to oops/WARN line offers the same kind of line, built from the open database, as its default text the first time (after a paste it offers the last text, as before); tested with fake ida_* modules. Fed back to --oops it gives exact on the MemLens demo kernel, Debian 13 dm-mod.ko, Ubuntu 6.8 amd64 and Android GKI 6.1 (arm64); tests/test_oops.py checks the round trip.
  • kflow: List static-key sites has a Block column: the size of the out-of-line block at the site's target, as bytes / insns. It is decoded with ida_ua.decode_insn (no change to the database) from the target up to and including the first instruction that does not go on to the next one (IDA's CF_STOP; on arm64, by their bytes: b, brk, ret, br and eret end it (also retaa, retab, braa, brab, braaz, brabz, eretaa, eretab), b.cond and blr (also blraa, blrab, blraaz, blrabz) never do), and ends before a join (an instruction a jump or call reference reaches, not one kflow added), an x86 int3 or the end of executable code: the block rule of tools/reach.py. At most 4096 instructions (then +); ? where an instruction cannot be decoded. Worked out only when IDA asks for a row, once per target. Tested only with fake ida_* modules; not yet run in IDA. Its IDA calls are covered by tests/check_ida_api.py and tests/check_ida_names.py (current totals in docs/VERIFICATION.md: 232 checks, 96 names).
  • Pseudocode: when the hidden-path sentence fails at one site (an exception), that site's comment is shown without the sentence and the error is reported once in the Output window. Before, one such error dropped all of kflow's comments in that function. Tested with fake ida_* modules.
  • Pseudocode comment of a static-key site: it now adds "nothing else in the database jumps or falls through to 0x..., so this pseudocode probably does not show that code" at a NOP site, or "the site is a jump here and nothing else in the database jumps or falls through to the next instruction 0x... (run when the key is on/off), so ..." at a site that is a jump, when, at the time the function is printed, the code the site does not run in this database (a NOP's target; the instruction after a site that is a jump) is an instruction with no ordinary flow into it and no jump or call reference except the NOP site's own and the references kflow recorded from sources that do not themselves jump there. A site that jumps to the very next instruction (eb 00) runs it in both key states: no sentence. Elsewhere the comment is as before. The flow part is what the test checks (fake ida_* modules); that Hex-Rays then leaves the code out is not checked in real IDA, hence "probably".
  • README: a shorter front door; the details moved to docs/FEATURES.md, docs/USAGE.md, docs/OUTPUT.md, docs/VERIFICATION.md and docs/limits.md (nothing removed); tests/test_oops.py checks the example WARNING: lines in docs/*.md too.

Built by an AI agent (Claude, operated by Nightshift Labs). Not yet run in real IDA.