Test di sicurezza offensiva basati su AI tramite agenti autonomi, direttamente nel tuo terminale.
<h1 align="center">Pensar Apex</h1> <p align="center"> Penetration testing basato sull'IA tramite agenti autonomi — direttamente nel tuo terminale. Esegui pentest blackbox e whitebox che esplorano, ragionano e fanno emergere vulnerabilità reali. </p> <p align="center"> Vuoi eseguirlo dal cloud o integrarlo con la tua CI/CD? Consulta <a href="https://docs.pensar.dev/console">Pensar Console</a>. </p> <p align="center"> <a href="https://www.npmjs.com/package/@pensar/apex"><img src="https://img.shields.io/npm/v/@pensar/apex?label=latest" alt="npm version"></a> <a href="https://www.npmjs.com/package/@pensar/apex"><img src="https://img.shields.io/npm/v/@pensar/apex/canary?label=prerelease&color=yellow" alt="npm prerelease version"></a> <!-- <a href="https://www.npmjs.com/package/@pensar/apex"><img src="https://img.shields.io/npm/dm/@pensar/apex" alt="npm downloads"></a> --> <a href="https://github.com/pensarai/apex/blob/canary/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache 2.0 License"></a> <a href="https://docs.pensar.dev/apex"><img src="https://img.shields.io/badge/docs-docs.pensar.dev/apex-purple?logo=readthedocs&logoColor=white" alt="Documentation"></a> <a href="https://discord.gg/pensar"><img src="https://img.shields.io/badge/Discord-Join%20Us-5865F2?logo=discord&logoColor=white" alt="Discord"></a> </p> <!-- <p align="center"> <img src="https://raw.githubusercontent.com/pensarai/apex/canary/screenshot.png" alt="Pensar Apex Screenshot" width="800"> </p> --> ## Casi d'uso ### Sviluppatori - Esegui `/pentest` prima di fare il merge di una PR — individua le vulnerabilità con la stessa naturalezza con cui esegui i test - Ottieni risultati concreti con punteggi di gravità, evidenze e correzioni suggerite — senza bisogno di competenze di sicurezza - Integra nella CI/CD tramite comandi CLI headless o Pensar Console ### Ingegneri della sicurezza - Distribuisci test swarm guidati da agenti su superfici d'attacco estese - Usa la modalità `/operator` per indagini manuali, concatenamento di exploit e validazione - Automatizza i flussi di test ripetitivi con una memoria persistente che si accumula tra gli incarichi - Scala su team e progetti tramite Pensar Console ## Installazione | Metodo | Comando | | ------------------------------- | ---------------------------------------------------- | | **Installazione rapida** (macOS/Linux) | `curl -fsSL https://pensarai.com/install.sh \| bash` | | **Homebrew** | `brew tap pensarai/tap && brew install apex` | | **npm** | `npm install -g @pensar/apex` | | **Windows** (PowerShell) | `irm https://www.pensarai.com/apex.ps1 \| iex` | ## Utilizzo Apri la TUI di Apex: ```bash pensar ``` ### CLI headless Esegui i pentest senza la TUI per scripting, CI o integrazione evalgate: ```bash # Basic pentest pensar pentest --target https://example.com # With extended thinking and task-driven mode pensar pentest --target https://example.com --extended-thinking --task-driven # Whitebox (with source code access) pensar pentest --target https://example.com --cwd ./my-app # Targeted pentest with specific objectives pensar targeted-pentest --target https://example.com --objective "Test authentication bypass" ``` | Flag | Comando | Descrizione | | ------------------------------ | ------------------------- | ---------------------------------------------- | | `--target <url>` | pentest, targeted-pentest | URL di destinazione (obbligatorio) | | `--cwd <path>` | pentest | Percorso del codice sorgente per la modalità whitebox | | `--mode <mode>` | pentest | `exfil` per pivoting ed estrazione di flag | | `--model <model>` | pentest, targeted-pentest | Modello IA (predefinito: selezione automatica) | | `--extended-thinking` | pentest | Abilita il pensiero esteso per i modelli supportati | | `--task-driven` | pentest | Abilita l'architettura task-driven (sperimentale) | | `--prompt <text\|@file>` | pentest | Guida personalizzata per l'agente | | `--threat-model <text\|@file>` | pentest | Modello di minaccia per guidare i test | | `--objective <text>` | targeted-pentest | Obiettivo di test (ripetibile) | ### Inferenza Hoonify Connetti **Hoonify** in `/providers` oppure imposta `HOONIFY_API_KEY`, poi seleziona un modello rilevato in `/models`. I comandi headless accettano `--model-provider hoonify --model <catalog-model-id>`. Consulta [Configurazione Hoonify](https://github.com/pensarai/apex/blob/canary/docs/hoonify.md) per il rilevamento dei modelli, i budget di token e i controlli live. ### Endpoint di inferenza personalizzati Collega un endpoint compatibile con OpenAI e un bearer token tramite la configurazione `customProviders` o la variabile d'ambiente del worker `APEX_CUSTOM_PROVIDERS`. Selezionalo con `--model-provider <id> --model <model>`, oppure scegli i suoi modelli dichiarati nel selettore `/models` dell'operatore. Consulta [configurazione inferenza personalizzata](https://github.com/pensarai/apex/blob/canary/docs/custom-inference.md) per le impostazioni GLM, la configurazione dei job headless e un test di connessione live. ### Logging Apex instrada il logging diagnostico/operativo attraverso un logger strutturato centralizzato (`src/core/logger`). Scrive JSON su una riga su **stderr** quando l'output non è un TTY — mantenendolo separato dallo stdout del programma e facile da inviare a una pipeline di log (ad es. CloudWatch) — e un output colorato e leggibile in un terminale interattivo. L'output CLI/TUI rivolto all'utente resta su stdout. Imposta il livello (dal più → al meno verboso: `debug` < `info` < `warn` < `error`, predefinito `info`): ```bash pensar pentest --target https://example.com --log-level debug # or --verbose / --quiet PENSAR_LOG_LEVEL=debug pensar ... # via environment PENSAR_DEBUG=1 pensar ... # back-compat alias for debug ``` Ordine di risoluzione: flag CLI → `PENSAR_LOG_LEVEL` → `PENSAR_DEBUG` → predefinito `info`. `PENSAR_LOG_FORMAT=json|pretty` forza il formato di output. Quando Apex viene eseguito come agente gestito, `PENSAR_LOG_LEVEL` è fornito dall'ambiente host. ### Tracing W&B Weave Trasmetti le tracce degli agenti a livello di step a Weights & Biases Weave per analisi e fine-tuning: ```bash export WANDB_API_KEY=your-key export WANDB_ENTITY=your-entity # WANDB_PROJECT defaults to "apex-traces" pensar pentest --target https://example.com ``` Le tracce includono passaggi di ragionamento, chiamate agli strumenti, utilizzo dei token e checkpoint di stato. Quando le credenziali non sono impostate, il tracing viene disabilitato silenziosamente. ### OpenTelemetry (Osservabilità) Apex emette span OpenTelemetry per esecuzioni degli agenti, chiamate LLM ed esecuzioni di strumenti tramite `@opentelemetry/api`. Gli span sono no-op a meno che il tuo processo non registri un SDK OpenTelemetry come tracer provider globale; Apex non include alcun SDK. Registra un SDK prima di importare il codice di Apex: - **Sentry**: installa `@sentry/node` ≥ 9.27 e aggiungi `Sentry.vercelAIIntegration()` alle tue integrazioni di `Sentry.init`. - **Qualsiasi backend OTel** (Honeycomb, Tempo, Datadog, ecc.): registra `@opentelemetry/sdk-node` con un exporter OTLP. Gli span seguono le [convenzioni semantiche OTel GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Per impostazione predefinita viene catturata solo la forma dello span (modello, conteggi dei token, latenza, nomi degli strumenti); imposta `AI_TRACE_RECORD_PAYLOADS=true` per registrare anche prompt, I/O degli strumenti e output. ## Container Kali Linux (opzionale) Per **prestazioni ottimali**, esegui Apex nel container Kali Linux incluso con strumenti di pentest preconfigurati: ```bash cd container cp env.example .env # add your API keys docker compose up --build -d docker compose exec kali-apex bash ``` All'interno del container, esegui: ```bash pensar ``` --- ### ⚠️ Uso responsabile Questo repository contiene strumenti esclusivamente per **test di sicurezza autorizzati**. Prima dell'uso, leggi e accetta la [Divulgazione sull'uso responsabile](https://github.com/pensarai/apex/blob/canary/RESPONSIBLE_USE.md).
