Skip to content

GITHUB.md

Latest commit

 

History

History
238 lines (193 loc) · 16.6 KB

GITHUB.md

File metadata and controls

238 lines (193 loc) · 16.6 KB
Raw

AirTell GitHub Operational Architecture & Repository Configurations

This document specifies the operational architecture, community governance, issue workflows, and automated AI review systems configured for the AirTell GitHub repository.

Table of Contents

  1. Governance & Repository Ownership
  2. Community Discussions Architecture
  3. Issue Templates & Triage Engine
  4. AI Code Review System (Gemini 4 Argon & Antigravity SDK)
  5. Release Automation (Release Please)
  6. Repository File Map

1. Governance & Repository Ownership

Repository ownership is declared globally via .github/CODEOWNERS to enforce architectural integrity across low-level CC2652 firmware bridges, UART line protocols, and side-channel analytics:

# Global repository owner: applies to all files across the entire codebase
* @ncouture

Operational Impact

  • Automatic Review Assignment: Any Pull Request modifying files in the repository automatically requests a review from @ncouture.
  • Branch Protection Alignment: Paired with branch protection on main requiring approved reviews from designated Code Owners before merging.
  • Workflow Authorization Gate: Serves as the authoritative source of truth for triggering automated AI code reviews.

2. Community Discussions Architecture

AirTell uses GitHub Discussions as an open RF salon and research exchange to segregate open-ended signal analysis from reproducible codebase defects. Full maintainer protocols and the pinned welcome post are documented in .github/DISCUSSIONS.md.

Discussion Categories

  1. 🎙️ RF Tradecraft & Signal Forensics: Timing side-channels, clock drift, Apple Continuity / Google Fast Pair reverse-engineering, and sanitized .pcap teardowns.
  2. 🛠️ Hardware Rigs & Testbed Engineering: CC2652 dongle flashing, LaunchPad / Sonoff antennas, attenuation, and VirtualRadioBus mock harnesses.
  3. ⚔️ Red Team Tradecraft & Stimulus Chains: Active SCAN_REQ stimulus timing, persistence across MAC rotation intervals, and physical perimeter tracking.
  4. 🛡️ Risk, Governance & Privacy Engineering: Fleet privacy posture evaluations, empirical tracking benchmarks, and sensitive facility threat modeling.
  5. 💡 Ideas, Feature Requests & Wild Experiments: Protocol extensions, Wireshark dissectors, and Streamlit visualization ideas.

Maintainer Triage Rules

  • Issues are for Bugs: Hardware desyncs, UART buffer underruns, packet parsing panics, and CI testbed failures.
  • Convert Questions to Discussions: Maintainers convert issues labeled question, research, or hardware-rig into Discussions rather than closing them.

3. Issue Templates & Triage Engine

Issue creation is governed by GitHub Issue Forms located in .github/ISSUE_TEMPLATE/:

1. Template Chooser (config.yml)

  • blank_issues_enabled: false: Disables unstructured issues to guarantee all submissions include essential RF/testbed telemetry.
  • Discussions Link: Directly routes general questions, PCAP sharing, and hardware showcases to GitHub Discussions.
  • Security Vulnerability Link: Points security researchers to GitHub Private Vulnerability Reporting (/security/advisories/new).

2. Bug Report Form (bug_report.yml)

Enforces mandatory collection of critical environmental telemetry:

  • Operating Topology: Dropdown selection (Topology A, Topology B, Topology C, CLI Side-Channel, UI Dashboard, or VirtualRadioBus).
  • Hardware Dongles & Firmware: CC2652 model, USB ports, and Sniffle firmware versions (e.g., CC2652P on /dev/ttyUSB0 with Sniffle v1.10.0).
  • Environment: OS and Python versions.
  • Reproduction Steps: Exact CLI commands and arguments.
  • Logs / Captures: Code-formatted blocks for stack traces and Wireshark errors.

3. Feature Request Form (feature_request.yml)

Requires contributors to articulate the research motivation, technical proposal, and alternative implementations considered.

4. AI Code Review System

AirTell deploys a specialized, automated code review agent built on the Google Antigravity SDK (google-antigravity) and powered by Gemini 4 Argon with High Thinking.

                           PR Event or Comment Trigger
                                        │
                                        ▼
                  ┌───────────────────────────────────────────┐
                  │ .github/workflows/code-review.yml         │
                  │ Tier 1: Actor Check (github.actor)        │
                  │ Resolve: PR_AUTHOR & REQUESTER            │
                  └─────────────────────┬─────────────────────┘
                                        │
                                        ▼
                  ┌───────────────────────────────────────────┐
                  │ scripts/code_review.py                    │
                  │ Tier 2: --verify-codeowners-only          │
                  │ Codeowner Authorization Check             │
                  └─────────────────────┬─────────────────────┘
                                        │
               ┌────────────────────────┴────────────────────────┐
               ▼                                                 ▼
        ❌ Unauthorized                                  ✅ Authorized
  (Requester not in CODEOWNERS                    (Requester in .github/CODEOWNERS;
   or empty PR author)                             PR author: codeowner or community)
               │                                                 │
  - Abort execution immediately                    - Load NotebookLM Research Context
  - Post policy warning to PR                      - Execute Gemini 4 Argon (Thinking=High)
                                                   - Post Review Report to PR & Step Summary

Architectural Skill Protocol

The review protocol is codified in .github/skills/code-review/SKILL.md and targets five core dimensions:

  1. Link Layer & Serial Protocol Rigor: CC2652 UART buffer flow control (2,000,000 baud), sync word detection, and FIFO buffer overflow protection during dense BLE bursts.
  2. Side-Channel & Timing Integrity: Microsecond precision hardware timestamp preservation (1 µs timer counters), zero-allocation hot loops, and jitter calculation stability.
  3. Multi-Radio Topologies: Cross-dongle clock synchronization and link-layer state tracking across Topology A, B, C, and VirtualRadioBus mock fidelity.
  4. Zero-Panic Parsers: Defense against hostile, fuzzed over-the-air BLE PDUs and proprietary beacons (Apple Continuity, Google Fast Pair, SmartTags).
  5. Code Hygiene: Modern Python (>=3.10) typing, Pydantic v2 schemas, and Ruff linting rules (E, F, W, I).

Google NotebookLM Grounding

The code reviewer is grounded in the authoritative AirTell Research NotebookLM Workspace ("AirTell Intel: 259 PoPETs + 2018 to 2026 Bluetooth related PDFs").

  • Dual-Tier Knowledge Loading: In addition to web URL grounding, scripts/code_review.py automatically ingests docs/AirTell-PoPETs.md (the synchronized offline research index of all 259 papers) directly into the agent context.
  • Empirical Validation: Reviews cross-reference link-layer heuristics, timing side-channels, and active stimulus patterns against empirical privacy research standards.

Dual-Tier Codeowner Authorization Policy on Community PRs

To prevent abuse of high-thinking reasoning compute while supporting open-source community contributions, workflow execution and automated reviews are strictly protected by a dual-tier authorization model:

  1. Tier 1 (Workflow Trigger Gate): In .github/workflows/code-review.yml, a job-level if: condition requires (github.actor == 'ncouture' || github.triggering_actor == 'ncouture'). Non-codeowners cannot allocate GitHub Actions runner instances or execute workflows.
  2. Tier 2 (Runner Codeowner Verification Gate): In scripts/code_review.py, verify_codeowner_authorization validates that the review requester is a verified repository codeowner listed in .github/CODEOWNERS. Codeowners can authorize and trigger automated code reviews on pull requests authored by external community contributors as well as internal codeowners.

If review requester authorization fails or the PR author is missing, scripts/code_review.py terminates immediately with exit code 1 and posts an explanatory policy notice to the PR, ensuring zero LLM API calls are dispatched.

CI/CD Workflow & Trigger Mechanics

The GitHub Actions workflow at .github/workflows/code-review.yml supports four on-demand trigger mechanisms:

  1. ChatOps Comment: A codeowner comments /review, /code-review, or /ai-review on a PR (issue_comment: [created]).
  2. Review Requested: A codeowner clicks "Request review" in the GitHub PR interface (pull_request: [review_requested]).
  3. Label Added: A codeowner adds the label code-review, ai-review, or review to the PR (pull_request: [labeled]).
  4. Manual Dispatch: A codeowner triggers the workflow via workflow_dispatch specifying the pr_number.

Local CLI Execution

Developers and codeowners can run the AI code review runner locally on their development machines:

# Review uncommitted staged changes
python scripts/code_review.py --staged

# Review local branch against origin/main and write output to a file
python scripts/code_review.py --base origin/main --output review.md

# Enforce codeowner policy locally (authorized on community PRs)
python scripts/code_review.py \
  --base origin/main \
  --enforce-codeowners \
  --pr-author "community-contributor" \
  --requester "ncouture"

5. Release Automation (Release Please)

AirTell automates semantic versioning, changelog generation, and GitHub releases using Google Release Please Action (googleapis/release-please-action@v5) with manifest-driven configuration.

                  Merge to main or Manual Dispatch
                                 │
                                 ▼
           ┌───────────────────────────────────────────┐
           │ .github/workflows/release-please.yml      │
           │ Tier 1: Actor Check (github.actor)        │
           └─────────────────────┬─────────────────────┘
                                 │
                                 ▼
           ┌───────────────────────────────────────────┐
           │ Runner: Tier 2 Codeowner Verification     │
           │ Dynamic .github/CODEOWNERS parsing        │
           └─────────────────────┬─────────────────────┘
                                 │
                        ┌────────┴────────┐
                        ▼                 ▼
                 ❌ Unauthorized    ✅ Authorized
                 (Halt runner)      (Execute release-please)
                                          │
                                          ▼
                                ┌───────────────────┐
                                │ Release Please v5 │
                                │ Manifest Strategy │
                                └───────────────────┘

Manifest-Driven Architecture

Release configuration and version tracking are maintained via root manifest files:

  • release-please-config.json: Configured for Python package airtell, updating pyproject.toml and src/airtell/__init__.py. Configured with bump-minor-pre-major: true and bump-patch-for-minor-pre-major: false for pre-1.0 semantic versioning.
  • .release-please-manifest.json: Tracks the current released version (0.2.0).

Dual-Tier Codeowner Release Gating

In strict compliance with repository security governance, release automation enforces defense-in-depth codeowner restriction:

  1. Tier 1 (Job-Level Trigger Gate): Evaluated before runner allocation: 
    if: github.actor == 'ncouture' || github.triggering_actor == 'ncouture'
    Ensures non-codeowners cannot allocate runners or trigger release workflows.
  2. Tier 2 (Runner-Level Codeowner Gate): The step Authorize Codeowner Execution parses .github/CODEOWNERS directly on the runner to dynamically verify the triggering actor prior to invoking googleapis/release-please-action@v5.

Release Please Workflow Mechanics

Configured in .github/workflows/release-please.yml:

  • Triggers: Runs on push to main and manual workflow_dispatch.
  • Runner & Runtime: Pinned to runs-on: ubuntu-24.04 using Node.js 24 native actions (actions/checkout@v6 and googleapis/release-please-action@v5).
  • Permissions: Requires contents: write (to create tags and releases), issues: write (to manage autorelease labels), and pull-requests: write (to manage release pull requests), paired with repository workflow permission can_approve_pull_request_reviews: true.
  • Concurrency: Governed by group: release-please-${{ github.ref }} with cancel-in-progress: false to ensure in-flight release tasks are not aborted prematurely.

6. Repository File Map

.github/
├── CODEOWNERS                       # Repository code ownership (* @ncouture)
├── DISCUSSIONS.md                   # Discussions welcome post & maintainer guidelines
├── ISSUE_TEMPLATE/
│   ├── bug_report.yml               # Structured bug report issue form
│   ├── config.yml                   # Template chooser configuration & discussion links
│   └── feature_request.yml          # Feature & protocol enhancement issue form
├── skills/
│   └── code-review/
│       └── SKILL.md                 # Gemini 3.8 Flash (Thinking=High) AirTell review skill
└── workflows/
    ├── code-review.yml              # CI/CD automated review workflow with codeowner gates
    └── release-please.yml           # Semantic release and changelog automation workflow

scripts/
└── code_review.py                   # Antigravity SDK review runner (symlinked to src/airtell/scripts/)

tests/
└── test_codeowner_enforcement.py    # Unit test suite verifying codeowner authorization policies

release-please-config.json           # Release Please manifest configuration (package airtell)
.release-please-manifest.json        # Release Please version tracker (0.2.0)