apex

<h1 align="center">Pensar Apex</h1>

<p align="center">
स्वायत्त एजेंटों का उपयोग करके AI-संचालित पेनेट्रेशन टेस्टिंग — सीधे आपके टर्मिनल में। ब्लैकबॉक्स और व्हाइटबॉक्स पेंटेस्ट चलाएँ जो खोजते हैं, तर्क करते हैं, और वास्तविक कमज़ोरियों को उजागर करते हैं।

</p>

<p align="center">
क्लाउड से चलाना चाहते हैं या इसे अपने CI/CD के साथ एकीकृत करना चाहते हैं? देखें <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&amp;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&amp;logoColor=white" alt="Documentation"></a>
  <a href="https://discord.gg/pensar"><img src="https://img.shields.io/badge/Discord-Join%20Us-5865F2?logo=discord&amp;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> -->

## उपयोग के मामले

### डेवलपर्स

- PR मर्ज करने से पहले `/pentest` चलाएँ — टेस्ट चलाने की तरह ही सहजता से कमज़ोरियों को पकड़ें
- गंभीरता स्कोर, साक्ष्य, और सुझाए गए समाधानों के साथ कार्रवाई योग्य निष्कर्ष प्राप्त करें — किसी सुरक्षा पृष्ठभूमि की आवश्यकता नहीं
- हेडलेस CLI कमांड या Pensar Console के माध्यम से CI/CD में एकीकृत करें

### सुरक्षा इंजीनियर्स

- बड़े हमला सतहों पर एजेंट-संचालित स्वार्म टेस्टिंग तैनात करें
- मैनुअल जाँच, एक्सप्लॉइट चेनिंग, और सत्यापन के लिए `/operator` मोड का उपयोग करें
- एंगेजमेंट्स के दौरान जमा होने वाली स्थायी मेमोरी के साथ दोहराए जाने वाले टेस्टिंग वर्कफ़्लो को स्वचालित करें
- Pensar Console के माध्यम से टीमों और परियोजनाओं में स्केल करें

## इंस्टॉलेशन

| विधि                          | कमांड                                              |
| ------------------------------- | ---------------------------------------------------- |
| **त्वरित इंस्टॉल** (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`       |

## उपयोग

Apex TUI खोलें:

```bash
pensar
```

### हेडलेस CLI

स्क्रिप्टिंग, CI, या evalgate एकीकरण के लिए TUI के बिना पेंटेस्ट चलाएँ:

```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"
```

| फ़्लैग                           | कमांड                   | विवरण                                    |
| ------------------------------ | ------------------------- | ---------------------------------------------- |
| `--target <url>`               | pentest, targeted-pentest | लक्ष्य URL (आवश्यक)                          |
| `--cwd <path>`                 | pentest                   | व्हाइटबॉक्स मोड के लिए सोर्स कोड पथ             |
| `--mode <mode>`                | pentest                   | पिवोटिंग और फ़्लैग निष्कर्षण के लिए `exfil`       |
| `--model <model>`              | pentest, targeted-pentest | AI मॉडल (डिफ़ॉल्ट: स्वतः-चयनित)              |
| `--extended-thinking`          | pentest                   | समर्थित मॉडलों के लिए विस्तारित सोच सक्षम करें  |
| `--task-driven`                | pentest                   | कार्य-संचालित आर्किटेक्चर सक्षम करें (प्रायोगिक) |
| `--prompt <text\|@file>`       | pentest                   | एजेंट के लिए कस्टम मार्गदर्शन                  |
| `--threat-model <text\|@file>` | pentest                   | परीक्षण का मार्गदर्शन करने के लिए थ्रेट मॉडल                  |
| `--objective <text>`           | targeted-pentest          | परीक्षण उद्देश्य (दोहराने योग्य)                  |

### Hoonify इन्फ़रेंस

`/providers` में **Hoonify** कनेक्ट करें या `HOONIFY_API_KEY` सेट करें, फिर
`/models` में एक खोजा गया मॉडल चुनें। हेडलेस कमांड
`--model-provider hoonify --model <catalog-model-id>` स्वीकार करते हैं। मॉडल खोज, टोकन बजट, और लाइव जाँच के लिए
[Hoonify सेटअप](https://github.com/pensarai/apex/blob/canary/docs/hoonify.md) देखें।

### कस्टम इन्फ़रेंस एंडपॉइंट

`customProviders` कॉन्फ़िगरेशन या `APEX_CUSTOM_PROVIDERS` वर्कर एनवायरनमेंट वेरिएबल के माध्यम से एक OpenAI-संगत एंडपॉइंट और बियरर टोकन लाएँ। इसे
`--model-provider <id> --model <model>` के साथ चुनें, या ऑपरेटर के `/models` पिकर में इसके घोषित मॉडल चुनें। GLM सेटिंग्स, हेडलेस जॉब कॉन्फ़िगरेशन, और एक लाइव कनेक्शन टेस्ट के लिए [कस्टम इन्फ़रेंस सेटअप](https://github.com/pensarai/apex/blob/canary/docs/custom-inference.md) देखें।

### लॉगिंग

Apex एक केंद्रीकृत संरचित लॉगर (`src/core/logger`) के माध्यम से डायग्नोस्टिक/ऑपरेशनल लॉगिंग रूट करता है। जब आउटपुट TTY नहीं होता है तो यह **stderr** पर एक-पंक्ति JSON लिखता है — इसे प्रोग्राम के stdout से अलग रखते हुए और लॉग पाइपलाइन (जैसे CloudWatch) में भेजना आसान बनाते हुए — और इंटरैक्टिव टर्मिनल में सुंदर, रंगीन आउटपुट देता है। उपयोगकर्ता-मुखी CLI/TUI आउटपुट stdout पर रहता है।

स्तर सेट करें (सबसे अधिक → सबसे कम विस्तृत: `debug` < `info` < `warn` < `error`, डिफ़ॉल्ट `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
```

रिज़ॉल्यूशन क्रम: CLI फ़्लैग → `PENSAR_LOG_LEVEL` → `PENSAR_DEBUG` → डिफ़ॉल्ट `info`।
`PENSAR_LOG_FORMAT=json|pretty` आउटपुट प्रारूप को बाध्य करता है। जब Apex एक प्रबंधित एजेंट के रूप में चलता है, तो `PENSAR_LOG_LEVEL` होस्ट एनवायरनमेंट द्वारा प्रदान किया जाता है।

### W&B Weave ट्रेसिंग

विश्लेषण और फ़ाइन-ट्यूनिंग के लिए चरण-स्तरीय एजेंट ट्रेस को Weights & Biases Weave पर स्ट्रीम करें:

```bash
export WANDB_API_KEY=your-key
export WANDB_ENTITY=your-entity
# WANDB_PROJECT defaults to "apex-traces"
pensar pentest --target https://example.com
```

ट्रेस में तर्क चरण, टूल कॉल, टोकन उपयोग, और स्टेट चेकपॉइंट शामिल हैं। जब क्रेडेंशियल सेट नहीं होते हैं, तो ट्रेसिंग चुपचाप अक्षम कर दी जाती है।

### OpenTelemetry (अवलोकनीयता)

Apex `@opentelemetry/api` के माध्यम से एजेंट रन, LLM कॉल, और टूल निष्पादन के लिए OpenTelemetry स्पैन उत्सर्जित करता है। स्पैन तब तक नो-ऑप होते हैं जब तक आपकी प्रक्रिया वैश्विक ट्रेसर प्रदाता के रूप में OpenTelemetry SDK पंजीकृत नहीं करती; Apex कोई SDK नहीं भेजता।

Apex कोड आयात करने से पहले एक SDK पंजीकृत करें:

- **Sentry**: `@sentry/node` ≥ 9.27 इंस्टॉल करें और अपने `Sentry.init` इंटीग्रेशन में `Sentry.vercelAIIntegration()` जोड़ें।
- **कोई भी OTel बैकएंड** (Honeycomb, Tempo, Datadog, आदि): OTLP एक्सपोर्टर के साथ `@opentelemetry/sdk-node` पंजीकृत करें।

स्पैन [OTel GenAI सेमांटिक कन्वेंशन्स](https://opentelemetry.io/docs/specs/semconv/gen-ai/) का पालन करते हैं। डिफ़ॉल्ट रूप से केवल स्पैन आकार (मॉडल, टोकन गणना, विलंबता, टूल नाम) कैप्चर किया जाता है; प्रॉम्प्ट, टूल I/O, और आउटपुट भी रिकॉर्ड करने के लिए `AI_TRACE_RECORD_PAYLOADS=true` सेट करें।

## Kali Linux कंटेनर (वैकल्पिक)

**सर्वोत्तम प्रदर्शन** के लिए, पूर्व-कॉन्फ़िगर किए गए पेंटेस्ट टूल्स के साथ शामिल Kali Linux कंटेनर में Apex चलाएँ:

```bash
cd container
cp env.example .env  # add your API keys
docker compose up --build -d
docker compose exec kali-apex bash
```

कंटेनर के अंदर, चलाएँ:

```bash
pensar
```

---

### ⚠️ ज़िम्मेदार उपयोग

इस रिपॉज़िटरी में केवल **अधिकृत सुरक्षा परीक्षण** के लिए टूल्स हैं।
उपयोग से पहले, कृपया [ज़िम्मेदार उपयोग प्रकटीकरण](https://github.com/pensarai/apex/blob/canary/RESPONSIBLE_USE.md) पढ़ें और सहमत हों।