Repository navigation
v0.0.7
·
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 fakeida_*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-exampleprints aWARNING:line built from the file's own__bug_table, the IDA dialog offers the same kind of line the first time, and--oopsalso takes the line itself. - List static-key sites has a Block column (
bytes / insnsof 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 ondm-mod.kofrom thekflow-try-module.zipasset. - 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.jsonidaVersions>=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%), thenfile:linewithout 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 withpython3 -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.pyfails on a README code line over 110 characters; on a kernel with the README's addresses (the demo kernel),tests/test_entry_stub.pychecks that each wrapped comment, unwrapped, is the code's own text. docs/VERIFICATION.md lists the try moduledm-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_64dm-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 arm64ext4.kodownload 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:--oopsalso takes the line itself, sopython3 -m kflow kernel.elf --oops "$(python3 -m kflow kernel.elf --oops-example)"givesexact, rc 0, on Debian 13dm-mod.koand 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 :,+0xor:<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.txtgaveno match, rc 1, nowno such file, rc 2; a barefunc+0x674/0x9d0is 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 22in the fake-IDA test, which has no other references; real IDA may show fewer), F5 indm_submit_bio(4zoned_enabledsites and theblock_splittracepoint; in the fake, all 5 comments end with the hidden-path sentence), and Go to oops/WARN line's first textWARNING: 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 thatud2. Labelled as fake-IDA text; kflow has not yet run in real IDA. Ondm-mod.ko,tests/test_entry_stub.pychecks every number and name of that paragraph against its run and the command line, andtests/test_oops.pychecks the quoted line against--oops-example. - Annotate's summary window (menu only) starts with the line kflow: Annotate finished (a plain line: the
TITLEprefix that IDAPython passes toask_ynis not documented forask_buttons), and reads as a result: the headlineN 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 13dm-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, andGo to oops/WARN line starts with a WARNING line built from this databasewhen 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 intools/kflow_headless.py's output, unchanged. Fake-IDA test ondm-mod.ko:22 of 22,press F5 in dm_submit_bio (5 hidden-path static-key sites); tested only with fakeida_*modules; not yet run in IDA. - Annotate's summary window is an
ida_kernwin.ask_buttonswindow 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.pyprints text as before. Tested only with fakeida_*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.pyalso checksask_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 DWARFvmlinuxhasfile: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 andfile:lineto every inlined copy), creditslinux_und.pyand the SDK exampleana_emu_out.py, and dates the "no public__jump_tabledecoder found" search. Every number re-measured withtools/reach.pyandpython3 -m kflowon 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 calledgic_handle_irq; IDA's name lookup gives the first one's start for both, so the dialog offeredgic_handle_irq+0x190/0xf4, which pasted back was not an exact match.oops.example_linenow skips a site whose offset is not below the printed size (the CLI's--oops-examplealready skipped such names; its output is unchanged). python3 -m kflow <kernel> --oops-exampleprints aWARNING: CPU: 0 PID: 1 at file:line func+0xoff/0xsizeline (with[module]for a module) built from the file's own__bug_table: the first WARN site with afile:linein a uniquely named function, so Go to oops/WARN line and--oopscan 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 fakeida_*modules. Fed back to--oopsit givesexacton the MemLens demo kernel, Debian 13dm-mod.ko, Ubuntu 6.8 amd64 and Android GKI 6.1 (arm64);tests/test_oops.pychecks 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 withida_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'sCF_STOP; on arm64, by their bytes:b,brk,ret,branderetend it (alsoretaa,retab,braa,brab,braaz,brabz,eretaa,eretab),b.condandblr(alsoblraa,blrab,blraaz,blrabz) never do), and ends before a join (an instruction a jump or call reference reaches, not one kflow added), an x86int3or the end of executable code: the block rule oftools/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 fakeida_*modules; not yet run in IDA. Its IDA calls are covered bytests/check_ida_api.pyandtests/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 (fakeida_*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.pychecks the exampleWARNING:lines in docs/*.md too.
Built by an AI agent (Claude, operated by Nightshift Labs). Not yet run in real IDA.