Bootcamp: od prázdného prostředí po první auditovatelnou zprávu
Sedm modulů, každý s reálnými API voláními proti běžící instanci. Cílem je, abyste po dokončení uměli založit šetření, přečíst zjištění s jejich důkazy, projít vztahový graf a vyexportovat auditovatelnou zprávu — beze zbytku přes REST API.
Pro koho: vývojáři integrující Progresus OSINT do vlastního systému a analytici, kteří chtějí rozumět tomu, co aplikace dělá pod kapotou. Předpoklad: běžící instance (lokálně přes docker-compose, nebo přístup ke sdílenému prostředí) a curl.
Modul 1 · Prostředí a API klíč
docker compose up -d zvedne PostgreSQL, Redis, Meilisearch a Kuzu; uv run alembic upgrade head aplikuje migrace. Aplikační server (just dev) a worker (just worker) běží jako dva samostatné procesy — bez workeru se založená šetření nikdy nepohnou dál než do stavu queued.
API klíč vytvoří správce instance jednou přes POST /v1/admin/api-keys. Plná hodnota se vrací pouze v této odpovědi a nikde jinde znovu k nahlédnutí — uložte si ji hned.
# vytvoření API klíče
curl -X POST -H "Content-Type: application/json" \
-d '{"name": "bootcamp", "scopes": ["investigations:read","investigations:write","reports:read"]}' \
https://<instance>/v1/admin/api-keys
export KEY="<vrácená hodnota key>"Modul 2 · Katalog zdrojů a první šetření
GET /v1/sources vrací všech osm zapojených poskytovatelů s kódem, kategorií a právním základem — z nich vybíráte rozsah šetření (scope.sources). Vynecháte-li rozsah, proběhnou všechny relevantní zdroje pro daný druh subjektu.
Šetření zakládá POST /v1/investigations. Pole idempotency_key je povinné — opakované odeslání se stejným klíčem vrátí totéž šetření místo duplicitního běhu, takže je bezpečné volání opakovat po timeoutu.
curl -H "Authorization: Bearer $KEY" \
https://<instance>/v1/sources
curl -X POST -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": "<project-uuid>",
"subject": {"kind": "company",
"identifiers": {"ico": "04543645"}},
"scope": {"sources": ["cz-ares","cz-isir","sanctions-eu"]},
"idempotency_key": "bootcamp-001"
}' \
https://<instance>/v1/investigationsModul 3 · Sledování průběhu
Šetření prochází stavy queued → collecting → validating → synthesizing → completed (nebo failed/cancelled). Stav zjistíte jedním dotazem, nebo si necháte přechody posílat průběžně přes SSE stream — pro bootcamp stačí polling co pár sekund.
Neběžící worker je nejčastější příčina „zaseklého" šetření ve stavu queued — viz modul 1.
# jednorázový dotaz na stav
curl -H "Authorization: Bearer $KEY" \
https://<instance>/v1/investigations/{id}
# průběžné události (SSE)
curl -N -H "Authorization: Bearer $KEY" \
https://<instance>/v1/investigations/{id}/eventsModul 4 · Zjištění, důkazy a kontrola integrity
Po dokončení GET /v1/investigations/{id}/findings vrátí seznam zjištění. Každé zjištění odkazuje na evidence_ids — konkrétní důkazy, ze kterých vzniklo, se zdrojem, časem pořízení a hashem obsahu.
GET /v1/findings/{finding_id} vrací navíc výsledek kontroly integrity: mapu jednotlivých kontrol a celkové passed. Integrita se přepočítává živě při čtení, ne jen jednou při zápisu — je to opakovatelně ověřitelný výpočet, ne uložený příznak, kterému musíte věřit naslepo.
curl -H "Authorization: Bearer $KEY" \
https://<instance>/v1/investigations/{id}/findings
curl -H "Authorization: Bearer $KEY" \
https://<instance>/v1/findings/{finding_id}
# -> { "checks": {...}, "passed": true }Modul 5 · Vztahový graf
Grafové endpointy žijí pod /v1/investigations/{id}/graph/… a jsou vždy ohraničené na dané šetření: sousedé entity (/neighbors/{entity_id}), hledání cesty mezi dvěma entitami (/path), centralita a detekce vlastnických cyklů (/cycles) — poslední jmenovaný typický vzorec schránkových struktur.
Aplikace (/app) vykresluje tentýž graf vizuálně nad stejným API — nic v prohlížeči nevidíte, co byste nedostali i přes curl.
curl -H "Authorization: Bearer $KEY" \
https://<instance>/v1/investigations/{id}/graph/cycles
curl -H "Authorization: Bearer $KEY" \
"https://<instance>/v1/investigations/{id}/graph/neighbors/{entity_id}"Modul 6 · Vyhledávání napříč šetřeními
GET /v1/search hledá nad subjekty, důkazy a zjištěními přes Meilisearch, vždy jen ve vašem tenantu — filtr tenantu se odvozuje z API klíče, nikdy z parametru dotazu. POST /v1/search/multi spustí několik dotazů různého druhu v jednom volání.
curl -H "Authorization: Bearer $KEY" \
"https://<instance>/v1/search?q=04543645&kind=entity"Modul 7 · Auditovatelná zpráva
POST /v1/reports s investigation_id a formátem (json, md nebo html) vygeneruje neměnnou zprávu s vloženým ověřovacím manifestem — kompletním seznamem hashů použitých důkazů, proti kterému lze zprávu dodatečně ověřit i offline. GET /v1/reports/{id}/download stáhne samotný soubor. PDF export je Plánováno.
Tím je bootcamp hotový — od API klíče po zprávu s dohledatelným důkazem, celé přes REST API.
curl -X POST -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"investigation_id": "<id>", "format": "md"}' \
https://<instance>/v1/reports
curl -H "Authorization: Bearer $KEY" \
https://<instance>/v1/reports/{report_id}/downloadCo dál
Vyzkoušejte bootcamp v aplikaci
Stejné kroky, bez psaní jediného curl příkazu.