taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

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())