From 5932931bec277ed4e0d703a227291df791f565c1 Mon Sep 17 00:00:00 2001 From: Pratheek Balakrishna Date: Mon, 22 Jun 2026 23:23:40 +0200 Subject: [PATCH 1/4] ci(dependabot): schedule weekly version updates (github-actions, pip) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Security updates were already on; this adds the separate version-update PRs. Scoped to the only two manifest-managed ecosystems — CI actions and host-side requirements.txt. The C upstream stays git-pinned via setup.sh and is intentionally excluded. Signed-off-by: Pratheek Balakrishna --- .github/dependabot.yml | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..9ea4c5c --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,29 @@ +# Dependabot version updates. +# +# Scope is deliberately narrow. The only manifest-managed dependencies in this +# repo are the GitHub Actions used by CI and the host-side Python tooling. +# The C firmware's upstream (debugprobe + FatFs + pico-sdk) is git-pinned by +# setup.sh into a gitignored upstream/ tree — that is intentional and is NOT a +# Dependabot ecosystem; do not add one for it. +# +# Dependabot SECURITY updates are enabled separately in repo settings; this file +# only adds scheduled VERSION-update PRs. +version: 2 +updates: + # CI actions (actions/checkout, upload-artifact, … pinned as floating tags today) + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "ci" + + # Host tooling + HIL test suites (requirements.txt: pyserial, Pillow) + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "chore" + # pyserial==3.5 is exact-pinned for USB-CDC transport stability on the bench; + # review any bump against the macOS HIL gotchas before merging. From 97d90dd5a870d9a9c2bd578b8e58adf04c8d5f33 Mon Sep 17 00:00:00 2001 From: Pratheek Balakrishna Date: Mon, 22 Jun 2026 23:23:40 +0200 Subject: [PATCH 2/4] chore(github): add CODEOWNERS and bug-report issue form CODEOWNERS binds the ruleset's code-owner-review rule (a no-op without the file) and names the two analyze.sh-pristine files. The YAML bug form requires the {"q":"status"} line (firmware ver) and prompts for the {"q":"lastfault"} crash dump; config.yml routes questions to Discussions and security reports to private advisories. Signed-off-by: Pratheek Balakrishna --- .github/CODEOWNERS | 15 ++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 70 +++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 +++ 3 files changed, 93 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..e6e6c03 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,15 @@ +# Code owners — drives review routing and binds the repo ruleset's +# "require code owner review" rule (which is a no-op without this file). +# +# See: https://docs.github.com/articles/about-code-owners + +# Default owner for everything +* @prat96 + +# The two files the analyze.sh gate requires to stay pristine +# (any warning in either fails CI) — keep eyes on them explicitly. +/firmware/c/src/hackagotchi_dashboard.c @prat96 +/firmware/c/src/cdc1_control.c @prat96 + +# CI / repo configuration +/.github/ @prat96 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..e6c28e3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,70 @@ +name: 🐞 Bug report +description: Something on the probe, dashboard, recorder, or host CLI misbehaves +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for filing a report. The fastest path to a fix is the **device's own status line** — + connect to the CDC1 control port and paste the output of `{"q":"status"}` below. + (Identify the control port by behavior: it's the one that answers with `"fw":"Hackagotchi"`.) + + - type: textarea + id: status + attributes: + label: '`{"q":"status"}` output' + description: 'Paste the full JSON line returned by the CDC1 control port. The `"ver"` field tells us the exact firmware build.' + render: json + validations: + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: What did you do, what did you expect, and what actually happened? + validations: + required: true + + - type: textarea + id: lastfault + attributes: + label: '`{"q":"lastfault"}` crash dump (if any)' + description: 'If the probe faulted/reset, paste the crash-box dump from `{"q":"lastfault"}`. Leave blank if not applicable.' + render: text + validations: + required: false + + - type: dropdown + id: area + attributes: + label: Affected area + description: Best guess — optional. + options: + - "Not sure" + - "DAP / SWD probe (CDC0 + debug)" + - "OLED dashboard" + - "UART black-box recorder / microSD" + - "CDC1 JSON control channel" + - "Host CLI (hackagotchi_ctl.py)" + - "Build / toolchain" + validations: + required: false + + - type: input + id: host-os + attributes: + label: Host OS + placeholder: "e.g. macOS 15.5, Ubuntu 24.04, Windows 11" + validations: + required: false + + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I'm on the latest release (or `main`) and the issue still reproduces. + required: false + - label: I searched existing issues and didn't find a duplicate. + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3ed1dea --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: 💬 Questions, flashing help & ideas + url: https://github.com/GhostRoboticsLab/Hackagotchi/discussions + about: How do I flash it? Build/bench setup? General questions and ideas go in Discussions. + - name: 🔒 Report a security vulnerability + url: https://github.com/GhostRoboticsLab/Hackagotchi/security/advisories/new + about: Privately report a vulnerability. See SECURITY.md for scope and the trust model first. From 12a16d543a4453bbff24e619334b826b4d2e30c9 Mon Sep 17 00:00:00 2001 From: Pratheek Balakrishna Date: Mon, 22 Jun 2026 23:23:40 +0200 Subject: [PATCH 3/4] docs(security): add security policy and trust model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Frames the bench-tool trust model (physical/USB access trusted) so reports target the real surface — CDC1 JSON parser, SD path handling, ISR-stack safety, DAP-stall-via-input — and points reporters at the already-enabled private vulnerability reporting. Signed-off-by: Pratheek Balakrishna --- SECURITY.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e01119d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,48 @@ +# Security Policy + +Hackagotchi is a **bench tool**: a CMSIS-DAP debug probe, a UART black-box +recorder, and an OLED companion, all running from one firmware image on a Seeed +XIAO RP2040. This policy frames what a "vulnerability" means for a device whose +entire job is to have privileged physical access to *another* board. + +## Trust model + +- **Physical and USB access is trusted.** The probe is designed to be plugged + into a host you control and wired to a target you own. That a debug probe can + halt, erase, and flash its SWD target — or reset itself to the bootloader over + `{"q":"bootsel"}` — is the **intended function**, not a vulnerability. +- **The host driving the USB-CDC ports is trusted.** Anyone who can open the + control port can already drive the probe. + +## In scope + +Bugs where *untrusted or malformed input* causes memory corruption, a hang, or a +crash on the device — i.e. failures of the firmware's own safety invariants: + +- Malformed `{"q":...}` JSON on the CDC1 control channel (parser/overflow bugs). +- Path/argument handling in the SD-backed commands (`{"q":"ls"}`, `{"q":"cat"}`, + config save) reachable from CDC1. +- Buffer/ISR-stack safety in USB and IRQ callbacks. +- Anything that **stalls the DAP path** through input alone (the probe must + never stall — see `docs/firmware-conventions.md` R1). +- Vulnerabilities in the host tooling (`host/hackagotchi_ctl.py`) that a + malicious *device* could exploit against the host. + +## Out of scope + +- "A debug probe can flash arbitrary firmware to its target" — that's the product. +- Attacks requiring physical modification of the board or a malicious host. +- The original v1 MicroPython prototype in `firmware/micropython/` (reference only). + +## Reporting + +Please report privately via GitHub's **[private vulnerability reporting](https://github.com/GhostRoboticsLab/Hackagotchi/security/advisories/new)** +(Security tab → "Report a vulnerability"). Include the firmware `"ver"` from +`{"q":"status"}` and a reproduction. This is a small open-source project — there +is no formal SLA, but reports in scope will be acknowledged and addressed on a +best-effort basis. + +## Supported versions + +Only the latest published [release](https://github.com/GhostRoboticsLab/Hackagotchi/releases) +is supported. Fixes land on `main` and ship in the next release. From 3c948df45fdf39a8281f417b5558c01559f1fef2 Mon Sep 17 00:00:00 2001 From: Pratheek Balakrishna Date: Mon, 22 Jun 2026 23:23:40 +0200 Subject: [PATCH 4/4] docs: add CITATION.cff and use a dynamic README release badge CITATION.cff enables the Cite-this-repository widget. The release badge was hardcoded to v1.0 while v1.1 shipped; switch to img.shields.io/github/v/release so it never goes stale. Signed-off-by: Pratheek Balakrishna --- CITATION.cff | 21 +++++++++++++++++++++ README.md | 2 +- 2 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 CITATION.cff diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..3b1ae82 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,21 @@ +cff-version: 1.2.0 +message: "If you use or reference Hackagotchi, please cite it using this metadata." +title: "Hackagotchi" +abstract: >- + A supercharged, pocket debugger for microcontrollers: firmware for a Seeed + XIAO RP2040 that runs a CMSIS-DAP SWD debug probe, a UART-to-microSD black-box + recorder, and a reactive OLED companion from one image on a single-core MCU. +type: software +authors: + - family-names: Balakrishna + given-names: Pratheek +repository-code: "https://github.com/GhostRoboticsLab/Hackagotchi" +url: "https://github.com/GhostRoboticsLab/Hackagotchi" +license: GPL-3.0-or-later +keywords: + - debug-probe + - cmsis-dap + - rp2040 + - swd + - firmware + - freertos diff --git a/README.md b/README.md index 235d79f..031ff45 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![Firmware CI](https://github.com/GhostRoboticsLab/Hackagotchi/actions/workflows/firmware-c.yml/badge.svg)](https://github.com/GhostRoboticsLab/Hackagotchi/actions/workflows/firmware-c.yml) [![Firmware: MIT](https://img.shields.io/badge/firmware%2Fc-MIT-blue.svg)](firmware/c/LICENSE) [![Project: GPL-3.0-or-later](https://img.shields.io/badge/project-GPL--3.0--or--later-blue.svg)](LICENSE) -[![Release](https://img.shields.io/badge/firmware-v1.0-green.svg)](https://github.com/GhostRoboticsLab/Hackagotchi/releases) +[![Release](https://img.shields.io/github/v/release/GhostRoboticsLab/Hackagotchi?color=green)](https://github.com/GhostRoboticsLab/Hackagotchi/releases)