Předběžný návod k nastavení a použití

Raný a záměrně nedoladěný návod, sepsaný 30. 9. 2026 podle toho, jak kód funguje dnes. Bude se rozrůstat. Každá část má štítek se stavem, takže hned vidíte, co je skutečné:

Funguje funguje už dnes a je veřejné.
Netestováno existuje v našem privátním kódu, ale zatím ho nikdo neprošel od začátku do konce.
Koncept zapojeno jen zčásti, se známými mezerami.
Plánováno ještě nestojí; popisujeme to, abyste věděli, kam směřujeme.

1. Co dnes existuje

Součást	Stav	Kde
Jádro skeneru: kontext, sken a skeptická vícekolová triáž	Funguje	Open source: github.com/Huge/nano-analyzer
Úloha pro merge requesty v GitLabu, která přidá jeden komentář s reportem	Netestováno	Privátní kód, sdílíme v rámci raného přístupu
GitHub Action	Koncept	Privátní kód, sdílíme v rámci raného přístupu
Příkaz `@budgetscan` v komentáři s limitem rozpočtu a termínu	Plánováno	—
Předplacené kredity a hostované skeny na inferenci s nulovou retencí dat	Plánováno	—

Veřejný repozitář je open-source jádro. Kromě něj udržujeme mnohem pokročilejší privátní kód; integrace do CI popsané níže žijí právě tam.

2. Rychlý start z příkazové řádky Funguje

Potřebujete Python 3.8+ a API klíč: OpenAI (výchozí model je gpt-5.4-nano) nebo OpenRouter (názvy modelů s lomítkem, například qwen/qwen3-32b). Volitelně si nainstalujte ripgrep (rg), aby triáž mohla prohledávat váš kód. Žádné další závislosti nejsou.

git clone https://github.com/Huge/nano-analyzer.git
cd nano-analyzer

# modely OpenAI (název modelu bez lomítka)
export OPENAI_API_KEY=sk-...
# nebo modely přes OpenRouter (název modelu s lomítkem)
export OPENROUTER_API_KEY=sk-or-...

# sken jednoho souboru nebo celého adresáře
python3 scan.py ./cesta/ke/zdrojakum

Každá fáze volá LLM, takže cena roste s množstvím kódu a počtem kol triáže. Začněte jedním adresářem a podívejte se, kolik to stojí, než skener pustíte na celý repozitář.

Nejčastější volby

Volba	Co dělá
`--model`	Model pro všechny fáze, např. `--model qwen/qwen3-32b`
`--parallel N`	Celkový počet souběžných volání API
`--triage-rounds N`	Počet skeptických kol na jeden nález (výchozí 5)
`--triage-threshold`	Nejnižší závažnost, která se triáží (výchozí `medium`)
`--min-confidence 0.7`	Zobrazí jen nálezy s alespoň touto jistotou
`--repo-dir ./`	Kořen repozitáře, který triáž prohledává; hodí se, když skenujete jen podadresář
`--extensions`, `--ignore-dirs`	Zúžení množiny skenovaných souborů
`--output-dir`	Kam se uloží výsledky (výchozí `~/nano-analyzer-results/<časové razítko>/`)

3. Jak číst výsledky

<časové razítko>/
├── summary.md              # začněte tady
├── findings/               # nálezy, které triáž přežily
│   └── VULN-001_<soubor>.md
├── triage_survivors.md     # souhrn potvrzených nálezů
├── triage.json             # všechny verdikty
├── triages/                # zdůvodnění u každého nálezu
└── <soubor>.md / .json / .context.md   # surový výstup po souborech

Jistota typu 80% [VVIVV→V] je podíl kol triáže, která nález uznala za platný; poslední písmeno je konečné rozhodnutí arbitra. Než podle nějakého nálezu začnete jednat, vždy si ho ověřte ručně.

4. Integrace s merge requesty v GitLabu Netestováno

CI úloha, která proskenuje soubory změněné v merge requestu a udržuje na něm jednu aktuální diskusi s reportem. Existuje v našem privátním kódu a zatím nebyla vyzkoušena od začátku do konce, takže počítejte s drobnými nedodělky. Soubory vám rádi pošleme v rámci raného přístupu (viz Dotazy).

Sestavte a publikujte image. Dockerfile nainstaluje git, ripgrep a volitelné nástroje pro vyhledávání v kódu:

docker build -f gitlab/Dockerfile -t registry.gitlab.com/<skupina>/<projekt>/nano-analyzer:latest .
docker push registry.gitlab.com/<skupina>/<projekt>/nano-analyzer:latest

Přidejte úlohu. Zkopírujte scan.py a složku gitlab/ do projektu, který chcete skenovat (wrapper zatím spouští scan.py z kořene toho projektu; toto balení se pravděpodobně změní), pak vložte šablonu a nastavte image:
```
include:
  - local: gitlab/.gitlab-ci.yml

variables:
  NANO_GITLAB_IMAGE: registry.gitlab.com/<skupina>/<projekt>/nano-analyzer:latest
```
Nastavte CI/CD proměnné (masked): NANO_GITLAB_API_TOKEN, tedy token, který smí zapisovat poznámky k merge requestu, a váš klíč k LLM, například OPENROUTER_API_KEY.
Otevřete merge request. Úloha běží jen v pipelinech merge requestů. Nejdřív upraví report na „This analysis is being updated...“, potom ho nahradí tabulkou s počty nálezů podle závažnosti pro každý soubor, stavem, časem a SHA commitu.

Jak se chová

Skenuje jen změněné soubory se známou příponou zdrojáků (výchozí režim changed); pro každý soubor jeden proces scan.py, spouštěné postupně.
Commit, který už analyzovala, přeskočí, a pokud někdo diskusi s reportem označí za vyřešenou, znovu ji otevře.
Komentář ukazuje jen počty; úplné nálezy jsou v artefaktech úlohy ve složce .nano-analyzer/gitlab/ (uchovávají se týden).

Proměnná	K čemu slouží
`NANO_GITLAB_SCAN_MODE`	`changed` (výchozí) nebo `all`
`NANO_GITLAB_SCAN_TARGET`	Co skenovat v režimu `all` (výchozí `.`)
`NANO_GITLAB_CHANGED_BASE`	Výslovný základní commit nebo větev pro diff
`NANO_GITLAB_ENFORCE_ONCE_PER_COMMIT`	Přeskočí už reportované commity (výchozí `true`)
`NANO_GITLAB_REOPEN_RESOLVED_THREAD`	Znovu otevře vyřešenou diskusi s reportem (výchozí `true`)
`NANO_GITLAB_RESOURCE_GROUP`	Klíč zámku, který zajistí, že skeny běží jeden po druhém
`NANO_GITLAB_MODEL`, `NANO_GITLAB_PARALLEL`, `NANO_GITLAB_TRIAGE_ROUNDS`	Předávají se skeneru

Bezpečnostní poznámka: API tokeny i klíče k LLM držte masked a chráněné a nezpřístupňujte je pipelinům z nedůvěryhodných forků.

5. GitHub pull requesty Koncept

V našem privátním kódu je definice GitHub Action, která spustí skener a udržuje na pull requestu jeden aktuální komentář. Je to koncept: vstupy pro cíl, model, paralelismus, limit velikosti, nastavení triáže, práh jistoty a adresář repozitáře jsou se skenerem propojené, ale několik dalších je zatím jen deklarováno a nezapojeno: format, scope, provider, nahrávání SARIF, nahrávání artefaktů a politika fail-*. Navíc spouští scan.py z pracovního prostoru volajícího, takže ji zatím nejde použít jako hotovou akci z jiného repozitáře.

Než to doladíme, nejjednodušší je pustit skener z příkazové řádky ve vlastním workflow. Je to netestovaná ukázka:

name: nano-analyzer
on: pull_request
permissions:
  contents: read
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/checkout@v4
        with:
          repository: Huge/nano-analyzer
          path: .nano-analyzer
      - name: Scan changed source files
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
        run: |
          git diff --name-only --diff-filter=AMRT "origin/${{ github.base_ref }}...HEAD" \
            | grep -E '\.(c|h|cc|cpp|go|py|js|ts|rs|java)$' > changed.txt || true
          [ -s changed.txt ] || { echo "No source changes"; exit 0; }
          xargs -a changed.txt python3 .nano-analyzer/scan.py \
            --model qwen/qwen3-32b --repo-dir . --output-dir scan-results
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: nano-analyzer-results
          path: scan-results

Pull requesty z forků ve výchozím stavu nedostanou tajné proměnné repozitáře. To je záměr: neobcházejte to přes pull_request_target spojené s checkoutem kódu z pull requestu.

6. Připravovaný příkaz `@budgetscan` Plánováno

Myšlenka: reviewer napíše komentář k pull nebo merge requestu a BudgetScan naplánuje sken, který se vejde do limitu i termínu. Nic z níže uvedeného zatím neběží a syntaxe se ještě může změnit.

Komentář	Záměr
`@budgetscan $0.25`	Rychlý průchod změněnými soubory s limitem $0.25
`@budgetscan $0.50 --max-delay 5m`	Hlubší průchod, který se blížícím pětiminutovým termínem přestane pouštět do nové práce a zveřejní částečný report s tím, co pokryl
`@budgetscan $5.00 --depth deep`	Vyšší limit se investuje do širšího kontextu a více kol triáže

Částky jsou v amerických dolarech; $0.50 a .5 znamenají totéž. Termíny vypadají třeba 90s, 5m nebo 1h.
Sken by nikdy neměl přesáhnout limit. Pokud limit nestačí ani na jediný soubor, dostanete srozumitelný report „nedostatečný rozpočet“ a nic se neúčtuje.
Selhání jsou vzácná a za selhaný sken se neplatí. Úplné obchodní podmínky zveřejníme před spuštěním.
Skutečné ceny za sken zveřejníme, až je změříme na benchmarcích.

7. Kam putuje váš kód

Stručně: hostované skeny běží u našeho partnera Kosmik Compute (Praha, nulová retence dat), nebo si open-source skener pustíte proti vlastnímu endpointu na vlastní infrastruktuře. Podrobnosti jsou v části Kam putuje můj kód?

8. Omezení

Falešné poplachy. Skenery s AI označí i věci, které se ukážou jako neškodné. Vícekolová triáž pomáhá a velmi si dáváme záležet na tom, aby falešných poplachů bylo co nejméně, přesto nálezy vždy ověřte ručně.
Přehlédnuté chyby. Celé třídy problémů (logické chyby, race conditions, chyby v kryptografii a autentizaci) může skener minout. Čistý sken neznamená, že je kód bezpečný.
Soubor po souboru. Každý soubor se skenuje samostatně, takže chyby vzniklé až souhrou více souborů se pravděpodobně přehlédnou.
Závislost na modelu. Různé modely najdou různé věci a dělají různé chyby.

9. Dotazy a raný přístup

Chcete privátní integrace, máte dotaz, nebo jste v návodu našli chybu? Napište nám (dev@ehlas.cz a safeAIwork@gmail.com).

← Zpět na přehled