new_finding.py (5163B)
1 # This file is part of GNU Taler 2 # (C) 2026 Taler Systems S.A. 3 # 4 # GNU Taler is free software; you can redistribute it and/or modify it under the 5 # terms of the GNU General Public License as published by the Free Software 6 # Foundation; either version 3, or (at your option) any later version. 7 # 8 # GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 9 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 10 # A PARTICULAR PURPOSE. See the GNU General Public License for more details. 11 # 12 # You should have received a copy of the GNU General Public License along with 13 # GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 14 """Scaffold a finding write-up from an episode's artifacts. 15 16 Turns the recorded action log into numbered steps a person can follow on a 17 device, and gathers the evidence paths, so the write-up only needs the analysis 18 and the suggested fix filled in. 19 20 python3 new_finding.py <episode-dir> [fingerprint] > my-finding.md 21 """ 22 23 from __future__ import annotations 24 25 import json 26 import sys 27 from pathlib import Path 28 29 # How each recorded action reads as an instruction to a person. 30 HUMAN = { 31 "tap_label": 'Tap **{arg}**.', 32 "tap_xy": "Tap the screen at {arg}.", 33 "long_press_label": 'Long-press **{arg}**.', 34 "type": 'Type `{arg}` into the text field.', 35 "scroll_down": "Scroll down.", 36 "scroll_up": "Scroll up.", 37 "back": "Press the back button.", 38 "rotate": "Rotate the device ({arg} = landscape).", 39 "uri": "Send the wallet this URI (share it into the app, or scan it as a QR code):\n `{arg}`", 40 "view_uri": "Open this link so the system hands it to the wallet:\n `{arg}`", 41 "process_death": "Kill the app's process (`adb shell am kill net.taler.wallet.fdroid.debug`) and reopen it.", 42 "relaunch": "Close the app and reopen it.", 43 "home_screen": "Go back to the main screen.", 44 } 45 46 SETUP_TEXT = { 47 "fresh": "a wallet with no data, developer mode on", 48 "funded": "a wallet with no data, developer mode on, then one completed " 49 "withdrawal of EUR:10 from the local bank", 50 "paid": "a wallet with one completed EUR:10 withdrawal and one completed " 51 "EUR:2 purchase", 52 "keep": "whatever state the previous scenario left behind", 53 } 54 55 56 def steps(actions: list[dict]) -> list[str]: 57 out = [] 58 for action in actions: 59 template = HUMAN.get(action["op"]) 60 if template is None: 61 out.append(f"Perform `{action['op']}` ({action.get('arg')!r}).") 62 else: 63 out.append(template.format(arg=action.get("arg"))) 64 return out 65 66 67 def main() -> int: 68 if len(sys.argv) < 2: 69 print(__doc__) 70 return 2 71 episode = Path(sys.argv[1]) 72 wanted = sys.argv[2] if len(sys.argv) > 2 else None 73 summary = json.loads((episode / "summary.json").read_text()) 74 findings = summary.get("findings", []) 75 if wanted: 76 findings = [f for f in findings if f.get("fingerprint") == wanted] 77 if not findings: 78 print(f"no findings in {episode}", file=sys.stderr) 79 return 1 80 finding = findings[0] 81 detail_files = sorted(episode.glob(f"*{finding['fingerprint']}*")) 82 actions = json.loads((episode / "actions.json").read_text()) \ 83 if (episode / "actions.json").is_file() else [] 84 scenario = summary.get("scenario") or summary.get("name", "") 85 setup = summary.get("setup", "keep") 86 87 print(f"""<!-- 88 This file is part of GNU Taler 89 (C) 2026 Taler Systems S.A. 90 91 GNU Taler is free software; you can redistribute it and/or modify it under the 92 terms of the GNU General Public License as published by the Free Software 93 Foundation; either version 3, or (at your option) any later version. 94 95 GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY 96 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 97 A PARTICULAR PURPOSE. See the GNU General Public License for more details. 98 99 You should have received a copy of the GNU General Public License along with 100 GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 101 --> 102 103 # TITLE ME 104 105 Found by the simulator in `{scenario}` ({finding['kind']}, fingerprint 106 `{finding['fingerprint']}`). 107 108 **Severity: TODO.** 109 110 ## What happens 111 112 ``` 113 {finding['detail'][:1200]} 114 ``` 115 116 Screen at the time: {summary.get('findings', [{}])[0].get('screen', '')} 117 118 ## Reproduce by hand 119 120 Starting point: {SETUP_TEXT.get(setup, setup)}. The local stack is the one 121 described in `simulator/README.md`; where a step mentions a URI, the bank or 122 the merchant produced it. 123 """) 124 for index, step in enumerate(steps(actions), start=1): 125 print(f"{index}. {step}") 126 print(f""" 127 Watch the app's log while doing this: 128 129 ```bash 130 adb logcat | grep -E 'taler-wallet|BackendManager|FATAL' 131 ``` 132 133 ## Why TODO 134 135 ## Suggested fix TODO 136 137 ## Evidence 138 139 Episode directory: `{episode}` (on tripwire). 140 """) 141 for path in detail_files: 142 print(f"* `{path.name}`") 143 print("* `actions.json` — the full recorded sequence, replayable with " 144 "`driver/replay.py`") 145 return 0 146 147 148 if __name__ == "__main__": 149 raise SystemExit(main())