Skip to content

Commit 4690042

Browse files
lukischlukisch
committed
docs: create German README_de.md and update check date in llms.txt
1 parent bc9d022 commit 4690042

4 files changed

Lines changed: 260 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Changelog
22

3+
## 2026-07-06
4+
5+
- Documentation: Created `README_de.md` containing a complete German translation.
6+
- Documentation: Added bilingual language selection links to the top of both `README.md` and `README_de.md`.
7+
- Documentation: Updated `llms.txt` metadata and `Last-checked` date to `2026-07-06`.
8+
39
## 2026-07-04
410

511
- Security/ethics: robots.txt is now honored for endpoints that came from an

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22
<img src="assets/banner_v2.svg" alt="ApiProber" width="100%" />
33
</p>
44

5+
<p align="right">
6+
<a href="README_de.md">🇩🇪 Deutsch</a> | <b>🇬🇧 English</b>
7+
</p>
8+
59
# ApiProber -- Passive API Discovery and Documentation Tool
610

711
[![ApiProber smoke tests](https://github.com/dev-bricks/apiprober/actions/workflows/tests.yml/badge.svg)](https://github.com/dev-bricks/apiprober/actions/workflows/tests.yml)

‎README_de.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
<p align="center">
2+
<img src="assets/banner_v2.svg" alt="ApiProber" width="100%" />
3+
</p>
4+
5+
<p align="right">
6+
<b>🇩🇪 Deutsch</b> | <a href="README.md">🇬🇧 English</a>
7+
</p>
8+
9+
# ApiProber -- Passives API-Discovery- und Dokumentations-Tool
10+
11+
[![ApiProber smoke tests](https://github.com/dev-bricks/apiprober/actions/workflows/tests.yml/badge.svg)](https://github.com/dev-bricks/apiprober/actions/workflows/tests.yml)
12+
13+
ApiProber ist ein abhängigkeitsfreies Python-CLI für passives API-Discovery. Es hilft Entwicklern und Maintainern, undokumentierte REST-Dienste zu kartografieren, das Live-Verhalten mit der API-Dokumentation zu vergleichen, Beobachtungen in SQLite zu persistieren und Markdown- oder JSON-Dokumentationen zu exportieren.
14+
15+
**Autor:** Lukas Geiger | **Lizenz:** MIT | **Python:** 3.8+ (nur Standardbibliothek)
16+
17+
---
18+
19+
## Einstieg
20+
21+
| Ziel | Befehl oder Datei |
22+
|---|---|
23+
| CLI ausprobieren | `python api_prober.py --help` |
24+
| Autorisierte API kartografieren | `python api_prober.py probe <base-url>` |
25+
| Dokumentation exportieren | `python api_prober.py export <service> --format md` |
26+
| Maschinenlesbaren Kontext lesen | [`llms.txt`](llms.txt) |
27+
| Schwachstelle vertraulich melden | [`SECURITY.md`](SECURITY.md) |
28+
29+
---
30+
31+
## Einsatzbereiche
32+
33+
- Interne REST-Dienste, für die keine OpenAPI-Datei existiert
34+
- Legacy-APIs, die eine leichtgewichtige Endpunkt-Dokumentation benötigen
35+
- Dokumentations-Audits, bei denen das Live-Verhalten mit den erwarteten Routen verglichen werden soll
36+
- Local-First-Sondierung vor dem Schreiben eines eigenen Clients oder SDKs
37+
- Passive Sicherheitsüberprüfungen mit expliziter Autorisierung
38+
39+
ApiProber ist kein Exploit-Framework, Schwachstellen-Scanner, Fuzzer oder Lasttester. Nutzen Sie es nur für APIs, die Sie besitzen oder zu deren Überprüfung Sie ausdrücklich berechtigt sind.
40+
41+
---
42+
43+
## Funktionen
44+
45+
- **Multi-Strategie-Erkennung:** OpenAPI-Erkennung, Wordlist-Probing, Pattern-Expansion (Mustererweiterung), Verfolgung von HATEOAS-Links
46+
- **Rate Limiting:** Konfigurierbare Verzögerung zwischen Anfragen (Standard: 500 ms)
47+
- **robots.txt-Konformität:** Automatische Berücksichtigung von Zugriffsbeschränkungen
48+
- **Authentifizierungs-Unterstützung:** Bearer-Token, API-Key, Basic-Auth
49+
- **JSON-Schema-Extraktion:** Automatische Ableitung von Schemata aus Antwort-Bodies
50+
- **SQLite-Persistenz:** Alle Ergebnisse werden in einer lokalen Datenbank gespeichert
51+
- **Export:** Markdown und JSON (OpenAPI-ähnlich)
52+
- **Fortsetzen:** Fortführung unterbrochener Probing-Sitzungen
53+
- **Standardmäßig ethisch:** Nur passive Erkundung, kein Fuzzing oder destruktive Methoden
54+
- **Keine Abhängigkeiten (Zero-Dependency):** Reines Python aus der Standardbibliothek (urllib, json, sqlite3, argparse, pathlib)
55+
56+
---
57+
58+
## Installation
59+
60+
Keine Installation erforderlich -- funktioniert ausschließlich mit der Python 3.8+ Standardbibliothek.
61+
62+
```bash
63+
git clone https://github.com/dev-bricks/apiprober.git
64+
cd apiprober
65+
66+
# Direkt aus dem Repository-Root ausführen
67+
python api_prober.py --help
68+
69+
# Oder als Paket installieren
70+
pip install -e .
71+
apiprober --help
72+
```
73+
74+
---
75+
76+
## Schnellstart
77+
78+
### Eine API untersuchen
79+
80+
```bash
81+
# Einfache Untersuchung
82+
python api_prober.py probe https://jsonplaceholder.typicode.com
83+
84+
# Tiefe Untersuchung mit benutzerdefinierter Verzögerung
85+
python api_prober.py probe https://api.example.com --depth 2 --delay-ms 1000
86+
87+
# Authentifizierte Untersuchung
88+
python api_prober.py probe https://api.example.com --auth-type bearer --auth-value "IHR_TOKEN"
89+
```
90+
91+
### Dienste verwalten
92+
93+
```bash
94+
# Alle untersuchten Dienste auflisten
95+
python api_prober.py list
96+
97+
# Details für einen bestimmten Dienst anzeigen
98+
python api_prober.py status jsonplaceholder
99+
100+
# Unterbrochene Untersuchung fortsetzen
101+
python api_prober.py resume jsonplaceholder
102+
```
103+
104+
### Ergebnisse exportieren
105+
106+
```bash
107+
# Als Markdown-Dokumentation exportieren
108+
python api_prober.py export jsonplaceholder --format md
109+
110+
# Als JSON (OpenAPI-ähnlich) exportieren
111+
python api_prober.py export jsonplaceholder --format json
112+
```
113+
114+
### Konfiguration
115+
116+
```bash
117+
# Aktuelle Konfiguration anzeigen
118+
python api_prober.py config --show
119+
120+
# Werte festlegen
121+
python api_prober.py config --set delay_ms 1000
122+
python api_prober.py config --set auth.type bearer
123+
```
124+
125+
### Umgang mit Anmeldedaten
126+
127+
Anmeldedaten (Credentials) werden außerhalb der versionierten `config.json` und der lokalen SQLite-Datenbank gehalten:
128+
129+
- **Empfohlen:** Setzen Sie die Umgebungsvariablen `APIPROBER_AUTH_VALUE` (und optional `APIPROBER_AUTH_TYPE`). Diese haben Vorrang vor allen Konfigurationsdateien und werden niemals auf die Festplatte geschrieben.
130+
- `python api_prober.py config --set auth.value "TOKEN"` schreibt den Wert in `config.local.json` -- eine gitignorierte Overlay-Datei neben `config.json` -- niemals in die versionierte `config.json`.
131+
- Konfigurationsauflösung: Standardwerte -> `config.json` -> `config.local.json` -> Umgebungsvariablen.
132+
- In der SQLite-Datenbank gespeicherte Run-Konfigurationen haben `auth.value` zensiert (`***REDACTED***`); `resume` liest das Credential erneut aus der aktuellen Konfiguration oder Umgebung ein.
133+
134+
---
135+
136+
## Erkennungsstrategien
137+
138+
ApiProber verwendet vier Strategien in absteigender Priorität:
139+
140+
1. **OpenAPI-Erkennung** (Priorität 1): Prüft auf `/swagger.json`, `/openapi.json`, `/api-docs` etc.
141+
2. **Wordlist-Probing** (Priorität 2): Testet ~140 gängige REST-Endpunkt-Pfade.
142+
3. **Pattern-Expansion** (Priorität 3): Erweitert Muster wie `/api/v{1,2,3}/{resource}`.
143+
4. **Response-Driven / HATEOAS** (Priorität 4): Folgt in Antwort-Bodies entdeckten Links.
144+
145+
---
146+
147+
## Sicherheit und Ethik
148+
149+
ApiProber ist für die verantwortungsvolle API-Erkundung konzipiert:
150+
151+
- **Standardmäßig schreibgeschützt (Read-only):** Nur GET, HEAD, OPTIONS (keine POST/PUT/DELETE-Anfragen ohne das Flag --test-all-methods).
152+
- **Integriertes Rate Limiting:** Konfigurierbare Verzögerung zwischen Anfragen.
153+
- **robots.txt-Konformität:** Berücksichtigt automatisch Zugriffsbeschränkungen.
154+
- **Transparenter User-Agent:** `ApiProber/0.1 (github.com/dev-bricks/apiprober; passive-discovery)`
155+
- **Kein Fuzzing, kein Exploiting:** Ausschließlich passive Erkennung.
156+
157+
---
158+
159+
## Projektstruktur
160+
161+
```
162+
ApiProber/
163+
+-- api_prober.py CLI-Einstiegspunkt
164+
+-- config.json Standardkonfiguration (keine Geheimnisse)
165+
+-- config.local.json Lokale Overrides inkl. auth.value -- gitignoriert
166+
+-- core/ Kernmodule
167+
| +-- config.py Konfigurationsverwaltung
168+
| +-- database.py SQLite-Persistenzschicht
169+
| +-- http_client.py HTTP-Client mit Rate Limiting
170+
| +-- robots.py robots.txt-Parser
171+
| +-- schema_extractor.py JSON-Schema-Inferenz
172+
+-- discovery/ Erkennungsstrategien
173+
| +-- orchestrator.py Strategie-Koordination
174+
| +-- openapi_detect.py OpenAPI/Swagger-Erkennung
175+
| +-- wordlist.py Wordlist-basiertes Probing
176+
| +-- pattern.py Pattern-Expansion
177+
| +-- response_driven.py HATEOAS-Link-Verfolgung
178+
| +-- method_tester.py HTTP-Methoden-Tests
179+
+-- export/ Export-Formate
180+
| +-- json_export.py JSON-Export
181+
| +-- markdown.py Markdown-Dokumentationsgenerator
182+
+-- wordlists/ Probe-Wordlists (~140 Pfade)
183+
| +-- common_rest.txt Gängige REST-Endpunkte
184+
| +-- admin_paths.txt Admin- und Managementpfade
185+
| +-- auth_endpoints.txt Authentifizierungsendpunkte
186+
| +-- swagger_paths.txt Swagger/OpenAPI-Pfade
187+
+-- data/ Laufzeitdaten (api_prober.db) -- gitignoriert
188+
+-- exports/ Generierte Dokumentation -- gitignoriert
189+
```
190+
191+
---
192+
193+
## Anwendungsfälle
194+
195+
- **Dokumentieren** von undokumentierten internen APIs
196+
- **Validieren** der API-Dokumentation gegen tatsächliches Verhalten
197+
- **Finden** erreichbarer Endpunkte in Systemen, zu deren Überprüfung Sie berechtigt sind
198+
- **Generieren** von API-Dokumentation für Legacy-Systeme
199+
- **Sicherheits-Audits** ausschließlich durch passive Aufklärung (Reconnaissance)
200+
201+
---
202+
203+
## Sichtbarkeit & Keywords
204+
205+
`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`, `authorized API inventory`, `REST endpoint mapper`
206+
207+
ApiProber steht in keiner Verbindung zu Cloudprober, probe-rs, aktiven Uptime-Monitoren oder semantischen Code-Suchmaschinen. Der Fokus liegt auf der lokalen, ratenlimitierten Dokumentation autorisierter REST-API-Oberflächen für Systeme, die Sie besitzen oder explizit überprüfen dürfen.
208+
209+
---
210+
211+
## Lizenz
212+
213+
MIT-Lizenz. Siehe [LICENSE](LICENSE).
214+
215+
---
216+
217+
## Entwicklung
218+
219+
Lokale Smoke-Tests ohne live Netzwerkzugriffe ausführen:
220+
221+
```bash
222+
python -m pytest -q
223+
python -m compileall -q .
224+
```
225+
226+
Die Live-Untersuchung von `jsonplaceholder.typicode.com` kann für manuelle Prüfungen zugeschaltet werden:
227+
228+
```bash
229+
set APIPROBER_RUN_NETWORK_TESTS=1
230+
python -m pytest -q test_smoke.py
231+
```
232+
233+
---
234+
235+
## Autor
236+
237+
Lukas Geiger -- [github.com/lukisch](https://github.com/lukisch)
238+
239+
Repository -- [dev-bricks/apiprober](https://github.com/dev-bricks/apiprober)
240+
241+
---
242+
243+
## Haftung / Liability
244+
245+
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.
246+
247+
Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.
248+
249+
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.

‎llms.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,4 +76,4 @@ ApiProber is not Cloudprober, probe-rs, an uptime monitor, a hardware debug
7676
probe, or a semantic code-search engine. It is a local Python CLI for documenting
7777
authorized REST API surfaces with read-only probing and SQLite persistence.
7878

79-
## Last-checked: 2026-06-12
79+
## Last-checked: 2026-07-06

0 commit comments

Comments
 (0)