chore: harden ApiProber packaging and CI

Lukas Geiger · Lukas Geiger · commit 715f89e26f63 · 2026-06-01T08:20:41.000+02:00
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
@@ -13,7 +13,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v9
+      - uses: actions/stale@v10
         with:
           stale-issue-message: >
             This issue has been automatically marked as stale because it has not had
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -0,0 +1,37 @@
+name: ApiProber smoke tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install test dependencies
+        run: python -m pip install --upgrade pip pytest
+
+      - name: Run smoke tests
+        run: python -m pytest -q
+
+      - name: Compile Python files
+        run: python -m compileall -q .
diff --git a/.github/workflows/welcome.yml b/.github/workflows/welcome.yml
@@ -14,19 +14,19 @@ jobs:
   welcome:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/first-interaction@v1
+      - uses: actions/first-interaction@v3
         with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-          issue-message: |
-            Welcome! 👋 Thanks for opening your first issue in this repository.
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          issue_message: |
+            Welcome! Thanks for opening your first issue in this repository.
 
             We'll review it as soon as possible. In the meantime:
             - Check if there's a similar issue already open
             - Add as much detail as possible (steps to reproduce, expected behavior, environment)
 
             If you'd like to contribute a fix, PRs are always welcome!
-          pr-message: |
-            Welcome! 👋 Thanks for your first pull request in this repository.
+          pr_message: |
+            Welcome! Thanks for your first pull request in this repository.
 
             A maintainer will review it soon. Please make sure:
             - [ ] Your changes are tested
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@ PLAN_*.txt
 
 # Python
 __pycache__/
+*.pyc
 *.py[cod]
 *$py.class
 *.egg-info/
@@ -12,6 +13,7 @@ build/
 *.egg
 
 # Runtime data
+*.db
 data/
 exports/
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,10 @@
+# Changelog
+
+## 2026-06-01
+
+- Fixed repository metadata after the move to `dev-bricks/apiprober`.
+- Made the flat `ApiProber` package installable through `pyproject.toml`.
+- Added a GitHub Actions smoke-test workflow.
+- Changed the live network smoke test to opt-in so CI remains deterministic.
+- Added `llms.txt` for machine-readable repository context.
+- Updated community workflow action versions and input names.
diff --git a/README.md b/README.md
@@ -2,16 +2,30 @@
   <img src="ApiProber_logo.jpg" alt="ApiProber" width="700">
 </p>
 
-# ApiProber -- Systematic API Discovery Tool
+# ApiProber -- Passive API Discovery and Documentation Tool
 
-Probe undocumented or poorly documented APIs. Discover endpoints through
-trial-and-error, map API structures, store results in SQLite, and generate
-documentation.
+ApiProber is a zero-dependency Python CLI for passive API discovery. It helps
+developers and maintainers map undocumented REST services, compare live
+behavior with API documentation, persist observations in SQLite, and export
+Markdown or JSON documentation.
 
 **Author:** Lukas Geiger | **License:** MIT | **Python:** 3.8+ (stdlib only)
 
 ---
 
+## Best Fit
+
+- Internal REST services where no OpenAPI file exists
+- Legacy APIs that need lightweight endpoint documentation
+- Documentation audits where live behavior should be compared with expected routes
+- Local-first reconnaissance before writing a proper client or SDK
+- Passive security review with explicit authorization
+
+ApiProber is not an exploit framework, vulnerability scanner, load tester, or
+fuzzer. Use it only on APIs you own or are allowed to assess.
+
+---
+
 ## Features
 
 - **Multi-Strategy Discovery:** OpenAPI detection, wordlist probing, pattern expansion, HATEOAS link following
@@ -32,11 +46,11 @@ documentation.
 No installation required -- works with Python 3.8+ standard library only.
 
 ```bash
-git clone https://github.com/lukisch/apiprober.git
+git clone https://github.com/dev-bricks/apiprober.git
 cd apiprober
 
-# Run directly
-python -m ApiProber --help
+# Run directly from the repository root
+python api_prober.py --help
 
 # Or install as package
 pip install -e .
@@ -51,47 +65,47 @@ apiprober --help
 
 ```bash
 # Basic probe
-python -m ApiProber probe https://jsonplaceholder.typicode.com
+python api_prober.py probe https://jsonplaceholder.typicode.com
 
 # Deep probe with custom delay
-python -m ApiProber probe https://api.example.com --depth 2 --delay-ms 1000
+python api_prober.py probe https://api.example.com --depth 2 --delay-ms 1000
 
 # Authenticated probe
-python -m ApiProber probe https://api.example.com --auth-type bearer --auth-value "YOUR_TOKEN"
+python api_prober.py probe https://api.example.com --auth-type bearer --auth-value "YOUR_TOKEN"
 ```
 
 ### Manage Services
 
 ```bash
 # List all probed services
-python -m ApiProber list
+python api_prober.py list
 
 # Show details for a specific service
-python -m ApiProber status jsonplaceholder
+python api_prober.py status jsonplaceholder
 
 # Resume interrupted probing
-python -m ApiProber resume jsonplaceholder
+python api_prober.py resume jsonplaceholder
 ```
 
 ### Export Results
 
 ```bash
 # Export as Markdown documentation
-python -m ApiProber export jsonplaceholder --format md
+python api_prober.py export jsonplaceholder --format md
 
 # Export as JSON (OpenAPI-like)
-python -m ApiProber export jsonplaceholder --format json
+python api_prober.py export jsonplaceholder --format json
 ```
 
 ### Configuration
 
 ```bash
 # Show current config
-python -m ApiProber config --show
+python api_prober.py config --show
 
 # Set values
-python -m ApiProber config --set delay_ms 1000
-python -m ApiProber config --set auth.type bearer
+python api_prober.py config --set delay_ms 1000
+python api_prober.py config --set auth.type bearer
 ```
 
 ---
@@ -114,7 +128,7 @@ ApiProber is designed for responsible API exploration:
 - **Default: Read-only** -- Only GET, HEAD, OPTIONS (no POST/PUT/DELETE unless `--test-all-methods` flag)
 - **Built-in rate limiting** -- Configurable delay between requests
 - **robots.txt compliance** -- Automatically respects access restrictions
-- **Transparent User-Agent** -- `ApiProber/0.1 (github.com/lukisch; passive-discovery)`
+- **Transparent User-Agent** -- `ApiProber/0.1 (github.com/dev-bricks/apiprober; passive-discovery)`
 - **No fuzzing, no exploitation** -- Purely passive discovery
 
 ---
@@ -154,11 +168,19 @@ ApiProber/
 
 ## Use Cases
 
-- **Reverse engineering** undocumented internal APIs
+- **Documenting** undocumented internal APIs
 - **Validating** API documentation against actual behavior
-- **Discovering** hidden endpoints in third-party services
+- **Finding** reachable endpoints in systems you are authorized to assess
 - **Generating** API documentation for legacy systems
-- **Security auditing** (passive reconnaissance only)
+- **Security auditing** through passive reconnaissance only
+
+---
+
+## Discoverability Keywords
+
+`passive API discovery`, `REST API documentation generator`, `OpenAPI detection`,
+`HATEOAS link crawler`, `local-first API reconnaissance`, `zero-dependency Python
+CLI`, `SQLite API inventory`, `ethical API probing`
 
 ---
 
@@ -168,17 +190,36 @@ MIT License. See [LICENSE](LICENSE).
 
 ---
 
+## Development
+
+Run the local smoke tests without live network probing:
+
+```bash
+python -m pytest -q
+python -m compileall -q .
+```
+
+The live `jsonplaceholder.typicode.com` probe is opt-in for manual checks:
+
+```bash
+set APIPROBER_RUN_NETWORK_TESTS=1
+python -m pytest -q test_smoke.py
+```
+
+---
+
 ## Author
 
 Lukas Geiger -- [github.com/lukisch](https://github.com/lukisch)
 
+Repository -- [dev-bricks/apiprober](https://github.com/dev-bricks/apiprober)
+
 ---
 
 ## Haftung / Liability
 
-Dieses Projekt ist eine **unentgeltliche Open-Source-Schenkung** im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß **§ 521 BGB** auf **Vorsatz und grobe Fahrlässigkeit** beschränkt. Ergänzend gelten die Haftungsausschlüsse aus GPL-3.0 / MIT / Apache-2.0 §§ 15–16 (je nach gewählter Lizenz).
+Dieses Projekt ist eine **unentgeltliche Open-Source-Schenkung** im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß **§ 521 BGB** auf **Vorsatz und grobe Fahrlässigkeit** beschränkt. Ergänzend gelten die Haftungsausschlüsse aus der MIT-Lizenz.
 
 Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.
 
 This project is an unpaid open-source donation. Liability is limited to intent and gross negligence (§ 521 German Civil Code). Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.
-
diff --git a/TODO.md b/TODO.md
@@ -0,0 +1,64 @@
+# Pre-Release TODO: ApiProber
+
+**Audit Date:** 2026-05-27
+**Auditor:** GPT / Codex automation
+**Target Repo:** `dev-bricks/apiprober`
+
+---
+
+## BLOCKER
+
+- [x] **Secrets:** No secret patterns found in tracked text files.
+- [x] **Private Data:** No known private email patterns found outside allowed metadata.
+- [x] **Hardcoded Paths:** No personal Windows or Unix home paths found.
+- [x] **Database Files:** No `.db` files are tracked.
+- [x] **.env Files:** No `.env` files are tracked.
+- [x] **BACH Internals:** No BACH-internal documents are tracked.
+- [x] **.gitignore:** Minimum gate entries are present.
+- [x] **LICENSE:** MIT license file is present.
+- [x] **README.md:** English README is present; German liability section is intentional and uses real umlauts.
+
+---
+
+## HIGH PRIORITY
+
+- [x] Add `CHANGELOG.md` before the next tagged release.
+- [ ] Decide whether generated local probe outputs should stay entirely in `data/` and `exports/` or move to a configurable runtime directory.
+
+---
+
+## MEDIUM PRIORITY
+
+- [x] Add CI for the smoke test.
+- [ ] Expand tests around auth handling, robots.txt decisions and export output.
+- [ ] Review whether the package import path should be normalized before PyPI publication.
+
+---
+
+## LOW PRIORITY
+
+- [ ] Add badges after CI exists.
+- [ ] Publish to PyPI after a final release review.
+
+---
+
+## STATUS
+
+| Category | Status | Notes |
+|----------|--------|-------|
+| Secrets | PASS | Gate scan found no secret patterns. |
+| Private Data (PII) | PASS | Known private email patterns were not found. |
+| .gitignore | PASS | Minimum entries are present. |
+| Language (English) | PASS | README passes the gate; German liability section is intentional. |
+| BACH Internals | PASS | No BACH-internal files are tracked. |
+| Database Files | PASS | No `.db` files are tracked. |
+| README.md | PASS | Present and release-oriented. |
+| LICENSE | PASS | MIT license present. |
+| **Overall** | **READY** | Final Gate Check passes after this audit. |
+
+**Audit Date:** 2026-05-27
+**Gate Check Exit Code:** `0`
+
+---
+
+*Template basis: MODULES/_templates/TODO_TEMPLATE.md*
diff --git a/config.json b/config.json
@@ -6,7 +6,7 @@
     "connect_timeout_s": 10,
     "read_timeout_s": 30,
     "max_retries": 2,
-    "user_agent": "ApiProber/0.1 (github.com/lukisch; passive-discovery)",
+    "user_agent": "ApiProber/0.1 (github.com/dev-bricks/apiprober; passive-discovery)",
     "respect_robots_txt": true,
     "skip_destructive": true,
     "strategies": ["openapi", "wordlist", "pattern", "response_driven"],
diff --git a/core/config.py b/core/config.py
@@ -18,7 +18,7 @@
     "connect_timeout_s": 10,
     "read_timeout_s": 30,
     "max_retries": 2,
-    "user_agent": "ApiProber/0.1 (github.com/lukisch; passive-discovery)",
+    "user_agent": "ApiProber/0.1 (github.com/dev-bricks/apiprober; passive-discovery)",
     "respect_robots_txt": True,
     "skip_destructive": True,
     "strategies": ["openapi", "wordlist", "pattern", "response_driven"],
diff --git a/llms.txt b/llms.txt
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/test_smoke.py b/test_smoke.py
