LM-Fingerprint

Rileva l'impronta dello stack di servizio dietro un endpoint chat compatibile con OpenAI.

Registra la contabilità del tokenizer, l'offset nascosto del template, il testo di validazione, la forma JSON/SSE, l'accettazione dei ruoli, i limiti dichiarati e gli header del gateway. Non carica pesi, non memorizza chiavi API e non chiede al modello chi sia.

Solo uso autorizzato: endpoint di tua proprietà, laboratori che controlli, bounty in scope, pentest autorizzati per iscritto. Vedi SECURITY.md. --api-key-env indica una variabile d'ambiente. La chiave non viene mai registrata.

Contents

1. Problem
2. What a fingerprint is
3. Architecture
4. Threat model
5. Install and the repro gate
6. First run
7. Against a live endpoint
8. Local Hugging Face tokenizers
9. CLI
10. Library
11. Reading a result JSON
12. Measured vs ModelPrint
13. Honesty rules
14. Nearby tools
15. License

Problema

La chat compatibile con OpenAI è un protocollo comune. vLLM, SGLang, un gateway di laboratorio e un rivenditore possono tutti parlare /chat/completions. Il campo model è un'etichetta. L'host può sostituire il backend, incapsulare il tokenizer o mettere un router davanti. Le sonde di personalità si spostano quando si sposta il system prompt.

Ciò che resta fermo è l'infrastruttura: come il server conta i token, quanti token di template nascosti aggiunge, il testo scritto dal suo validatore, il dialetto SSE, quali ruoli accetta, il numero che riporta quando max_tokens è assurdo, gli header Server / del provider.

Questa è la domanda a cui risponde lo strumento: quale stack sta gestendo questo percorso di chat? Non quale checkpoint, non quale processo è in ascolto sulla porta, non chi ha scritto una completion.

ModelPrint si è posto la stessa domanda in un browser con nove sonde. Questo pacchetto ne è la forma CLI e libreria: sonde versionate, libreria registrabile, confronto a coppie, drift e un percorso tokenizer locale che non chiama mai un'API di Inference ospitata.

Cos'è un'impronta

Un'impronta è un record JSON versionato dei value delle sonde. Ogni sonda deve restituire lo stesso valore quando lo stesso stack viene colpito due volte. Timestamp, id di richiesta, latenza e chiavi vengono rimossi.

I conteggi del tokenizer riutilizzano i testi di ModelPrint 1.0.0 (MIT, unclecode/modelprint), identici byte per byte, meno una baseline di un carattere "a" così un template nascosto si annulla. Quei quattro numeri sono una proiezione della mappa di encode (T). Conteggi uguali non significano (T_1 \equiv T_2). GPT-2 e OPT collidono su di essi; l'hash della pipeline rust no.

hf_identity (solo percorso HF locale) è lo SHA-256 di quel commitment della pipeline più l'hash del chat-template. Stessa (T) e stesso template corrispondono (tiny-gpt2 / gpt2). È famiglia + template, non un checkpoint.

Architettura

Struttura:

src/lm_fingerprint/
  cli.py         argparse. --api-key-env only. No --api-key.
  client.py      HttpTransport, InProcessTransport, redact_secrets
  probes.py      23 ProbeSpec rows (tokenizer / errors / shape / roles / limits / proxy)
  engine.py      run suite → Fingerprint
  schema.py      schema_version=1, probe_suite_version=lm-fingerprint-probes-v1
  similarity.py  weighted exact-match, coverage, confidence, library rank, drift
  library.py     enroll / match. Packaged rows are synthetic fixtures
  synthetic.py   in-process stacks for tests and the shipped library
  hf.py          local AutoTokenizer + named validation profile. No weights
  localmap.py    encode-pipeline-v2 commitment (rust tokenizer.json)
  proof.py       measured ModelPrint 9-probe identity
  report.py      text reports
  data/library.json

Due percorsi verso la stessa suite di sonde:

live endpoint                         local Hub tokenizer (optional [hf])
     |                                         |
 HttpTransport.chat                      HfChatTransport
 POST /chat/completions                  encode / chat_template for counts
     |                                   synthetic profile for errors/shape
     +------------------+----------------------+
                        |
                   engine.run_probes
                        |
              Fingerprint (JSON, keyless)
                        |
          compare | match | drift | enroll

Scrittura delle sonde: docs/PROBES.md. Mappa dei moduli: docs/ARCHITECTURE.md.

Modello di minaccia

Una corrispondenza è infrastruttura condivisa. Un laboratorio può servire due checkpoint su un unico stack. Un router può rispondere con il proprio wrapper degli errori. L'accordo sui conteggi non è identità di (T).

Installazione e gate di riproducibilità

Python 3.10+. Il runtime principale è la libreria standard.

git clone https://gitlab.com/WattoCyber/lm-fingerprint.git
cd lm-fingerprint
pip install -e ".[dev]"
PYTHONPATH=src python3 scripts/repro.py

Attenditi REPRO_OK. Questo gate è offline: niente GPU, niente API di produzione. I test HF locali vengono saltati se il tokenizer non è in cache.

pip install -e ".[hf]"    # transformers, for fingerprint-hf / verify-hf

Prima esecuzione

lm-fingerprint list-probes
lm-fingerprint list

list stampa gli stack inclusi: openai-chat-strict, glm-compat, router-openai, permissive-compat. Sono fixture, non provider raccolti. Confrontane due senza rete:

from lm_fingerprint.client import InProcessTransport
from lm_fingerprint.engine import fingerprint_endpoint
from lm_fingerprint.similarity import compare_fingerprints
from lm_fingerprint.synthetic import SYNTHETIC_STACKS, handler_for

def fp(stack_id):
    t = InProcessTransport(handler_for(stack_id), headers=SYNTHETIC_STACKS[stack_id].headers)
    return fingerprint_endpoint(t, model=f"synthetic/{stack_id}", base_url=f"inprocess://{stack_id}")

print(compare_fingerprints(fp("openai-chat-strict"), fp("router-openai"))["note"])

Stesso tokenizer di parole, errori e header diversi. Il punteggio si attesta intorno a 0.58. I quattro conteggi di ModelPrint corrispondono; questo strumento non lo definisce uno stack condiviso.

Contro un endpoint live

lm-fingerprint fingerprint \
  --base-url https://your-lab.example/v1 \
  --model the-label \
  --api-key-env OPENAI_API_KEY \
  --out lab.json

lm-fingerprint match --fingerprint lab.json
lm-fingerprint enroll --fingerprint lab.json --stack-id my-lab --library my-lib.json

Non passare la chiave da riga di comando. Non fare scraping di API di produzione per riempire una libreria pubblica.

Tokenizer Hugging Face locali

lm-fingerprint fingerprint-hf --model sshleifer/tiny-gpt2 --local-files-only
lm-fingerprint verify-hf --local-files-only

I conteggi provengono da apply_chat_template quando esiste un template, altrimenti da encode(..., add_special_tokens=False). La tassonomia degli errori proviene da un profilo sintetico nominato (default openai-chat-strict) così l'esecuzione resta offline. Gli handle remoti (https://, api://, …) vengono rifiutati.

CLI

lm-fingerprint list-probes
lm-fingerprint list [--library PATH]
lm-fingerprint fingerprint --base-url URL --model MODEL --api-key-env VAR [--out PATH]
lm-fingerprint fingerprint-hf --model HANDLE [--profile NAME] [--local-files-only]
lm-fingerprint verify-hf [--models a,b,c] [--local-files-only]
lm-fingerprint prove [--local-files-only]
lm-fingerprint compare --a a.json --b b.json
lm-fingerprint match --fingerprint a.json [--library PATH]
lm-fingerprint drift --baseline old.json --current new.json
lm-fingerprint enroll --fingerprint a.json --stack-id ID --library PATH
lm-fingerprint export --fingerprint a.json

Non esiste il flag --api-key. I JSON più vecchi di wireprint-fingerprint / stackprint-fingerprint vengono ancora caricati.

Libreria

from lm_fingerprint import (
    StackLibrary,
    compare_fingerprints,
    fingerprint_endpoint,
    fingerprint_hf,
    match_library,
)
from lm_fingerprint.client import HttpTransport

fp = fingerprint_endpoint(HttpTransport(url, api_key=key), model="x", base_url=url)
hit = match_library(fp, StackLibrary.load())
local = fingerprint_hf("sshleifer/tiny-gpt2", local_files_only=True)

Leggere un JSON di risultati

schema_version = 1, probe_suite_version = lm-fingerprint-probes-v1.

Confronto: exact-match pesato sulle sonde che sono ok e stable su entrambi i lati. La confidenza è score × coverage. Il match con la libreria riporta certainty (exact / strong / possible / unknown) e il margine rispetto al secondo vicino.

Misurato vs ModelPrint

Esegui di nuovo:

lm-fingerprint prove --local-files-only

Stesso residuo di ModelPrint (nove sonde in probes/index.js). Il loro README è la regola di punteggio: impronte corrispondenti provano infrastruttura condivisa, non identità.

Approfondimento: docs/PROOF.md.

Regole di onestà

1. Una corrispondenza è infrastruttura condivisa, non lo stesso checkpoint.
2. I vettori di conteggio sono una proiezione di (T). Non sono (T).
3. La libreria inclusa è sintetica. L'utente registra esecuzioni autorizzate.
4. fingerprint-hf non carica mai pesi e non chiama mai Inference ospitata.
5. Le chiavi provengono da --api-key-env. Gli artefatti non devono contenere sk- o Authorization.
6. scripts/repro.py è il gate del prodotto. Non dichiarare verde se non l'hai appena eseguito.

Strumenti correlati

Licenza

MIT. Vedi LICENSE. I testi del tokenizer di ModelPrint restano MIT (unclecode/modelprint) e identici byte per byte.