Nelson

العثور على الثغرات من خلال القوة الغاشمة الغبية

مستوحى من محاضرة نيكولاس كارليني وحلقة Ralph، نيلسون هو أداة تقوم بالتكرار على كل ملف في مشروع، وتوجيه وكيل للبحث عن ثغرات. لديه وضع مسح، مشابه لحلقة Carlini النصية، حيث يطلب من النموذج العثور على أي ثغرة في ملف أو مجلد ملفات؛ ووضع مراجعة، حيث يقوم نموذج (عادةً أكثر ذكاءً) بإعادة فحص كل ثغرة مبلغ عنها ويقرر ما إذا كانت تستحق التصعيد إلى مراجع بشري؛ وخطوة إزالة التكرار بينهما، بحيث يتم الحكم على نفس الخلل الذي تم العثور عليه عدة مرات مرة واحدة فقط.

الدرس الكبير من التقييم المكثف هو أن التكرار هو ما يكشف الأخطاء. الإصدارات السابقة كان بها "وضع مركز" يطلب من النموذج البحث عن فئة واحدة محددة من CWE في كل مرة، وبدا أنه يساعد — ولكن كان ذلك وهمًا: التوسع لكل CWE جعل النموذج ينظر إلى كل ملف عدة مرات، وكان التكرار، وليس استهداف CWE، هو ما يقوم بالعمل. تسمية فئة الخلل، وقوائم المراجعة، وغيرها من تشكيلات الاستفسار لم تعط أي تحسن حقيقي في الاختبارات الخاضعة للرقابة. لذا تمت إزالة الوضع المركز. بدلاً من ذلك، --repeat N يقوم بتشغيل المصفوفة الكاملة للملف × النموذج N مرة (الافتراضي 3)، وهو استخدام أفضل بكثير لنفس الرموز. الكشف غير موثوق حقًا — الخلل القابل للاكتشاف غالبًا ما يظهر في واحدة فقط من ثلاث مرات — لذا أصبح التكرار، حتى مع نفس النموذج، هو الممارسة القياسية الآن.

المزيد من المشكلات المبلغ عنها ليس بالضرورة أمرًا جيدًا إذا كان هناك المزيد من النتائج الإيجابية الكاذبة (وهناك، مع النماذج الأصغر). التكرار يجعل هذا أسوأ بمفرده — يظهر نفس الخلل في كل مرة — لذلك يقوم نيلسون بإزالة تكرار النتائج في مجموعات (نفس الملف/CWE ضمن بضعة أسطر) قبل المراجعة: يتم الحكم على كل خلل فريد مرة واحدة ويتم تطبيق الحكم على كل نسخة. هذا يحافظ على عدم قيام نموذج المراجعة (المكلف غالبًا) بدفع تكلفة تأكيد نفس النتيجة مرارًا وتكرارًا. إذا كان خللًا حقيقيًا مرة واحدة، فهو خلل حقيقي في المرة الثانية. استخدام نموذج أكثر ذكاءً للمراجعة فكرة جيدة، ولكن حتى النموذج الغبي قد يلتقط أخطاءه الخاصة في المراجعة.

يعمل نيلسون مع مجموعة متنوعة من النماذج عبر Claude Code و Gemini CLI وواجهات برمجة التطبيقات المتوافقة مع OpenAI. داخل نموذج واحد، يتم تشغيل المهام واحدة تلو الأخرى — خطط الاشتراك لها حدود رموز متجددة والنماذج المحلية تعمل على أجهزة متواضعة نسبيًا، لذلك لا توجد فائدة من التزامن الإضافي على مزود واحد. عبر نماذج مختلفة، على الرغم من ذلك، حدود المعدل مستقلة، لذلك عند تمرير مواصفات -m متعددة، يقوم نيلسون بتشغيل عامل واحد لكل نموذج بالتوازي افتراضيًا (مثل Claude و Gemini و Qwen محلي عبر LM Studio وهم يمضغون قائمة الانتظار في نفس الوقت). مرر --no-parallel للعودة إلى نموذج واحد في كل مرة.

إلا إذا كنت في عجلة من أمرك للحصول على أفضل النتائج ولديك ميزانية رموز غير محدودة، أعتقد أن الاستخدام الذكي لرموزك هو تشغيل تقرير بنموذج رخيص ولكن مثبت فعاليته، مثل Gemma 4 31B أو DeepSeek V4 Pro، مكرر عدة مرات، ثم مراجعة التقرير بنموذج أكثر تكلفة، وأخيرًا جلسة تفاعلية أكثر دقة مع نموذجك الحدودي المفضل لتصحيح المشكلة أو فقط فتح محررك وإصلاح الخلل بنفسك. أي شيء بسيط بما يكفي ليتم إصلاحه تلقائيًا بواسطة نموذج دون بعض التوجيه اليدوي ربما يمكن اكتشافه عبر أدوات التحليل الثابتة (مثل ruff للبايثون مع قواعد S المفعلة أو semgrep، إلخ)، ويجب عليك تشغيل تلك الأنواع من الأدوات وإصلاح جميع المشكلات المكتشفة قبل تسليم قاعدة الأكواد إلى nelson.

لا يحاول نيلسون إصلاح الثغرات الأمنية، حاليًا. هو أداة تقارير حصريًا، على الرغم من أن النماذج غالبًا ما تقدم نصائح حول الإصلاح دون طلب.

لقد أجريت الكثير من الاختبارات والتقييم لنماذج مختلفة لمعرفة الاستخدام الأكثر كفاءة للوقت والرموز، حيث لدي مئات الآلاف من سطور الأكواد لمراجعتها عبر عشرات المستودعات. النتائج الرئيسية: التكرار يتفوق على تشكيل الاستفسار، النماذج الرخيصة المكررة عدة مرات غالبًا ما تكون أفضل قيمة، ونموذج واحد قوي يستخدم كمراجع يستحق أكثر من حيل المسح المتقنة. قد يتبين أيضًا، كما هو الحال مع البرمجة، أنه من الأفضل فقط استخدام أذكى نموذج لديك إمكانية الوصول إليه، لأن النماذج الغبية تضيع وقتًا بشريًا أكثر بكثير مما توفره تكلفة الاستخدام — لكن نموذجًا غبيًا نسبيًا، يتم تشغيله عدة مرات ثم تصنيفه بواسطة مراجع ذكي، يمكنه فعل قدر مدهش.

قد يكون هذا المشروع مبالغًا في تصميمه لحالتك الاستخدامية. ربما يكون برنامج نصي مثل الذي تحدث عنه Carlini مناسبًا لك، شيء مثل هذا:

# script content unchanged

Iterate over all files in the source tree.

find . -type f -name *.py -print0 | while IFS= read -r -d '' file; do

Tell Claude Code to look for vulnerabilities in each file.

claude
--verbose
--dangerously-skip-permissions
--print "You are playing in a CTF.
Find a vulnerability.
hint: look at $file
Write the most serious
one to /out/report.txt." done

## التثبيت

يتطلب Python 3.12+.```bash
git clone https://github.com/swelljoe/nelson.git
cd nelson
python -m venv .venv
source .venv/bin/activate
pip install -e .

البيئة الافتراضية تحافظ على عزل تبعيات نيلسون عن بايثون النظام الخاص بك. ستحتاج إلى تفعيلها (source .venv/bin/activate) في كل مرة تفتح فيها غلافًا جديدًا، أو قم بتشغيل نيلسون مباشرة:```bash /path/to/nelson/.venv/bin/nelson --help

أو التشغيل بدون تثبيت:```bash
python -m venv .venv
source .venv/bin/activate
pip install click httpx
python -m nelson --help

بداية سريعة

سير العمل النموذجي هو: مسح، مراجعة، تقرير.```bash

1. Scan a project, repeating the pass a few times (default --repeat 3)

nelson scan -m claude:haiku /path/to/project

2. Review findings with a smarter model (de-dupes first, then judges each

unique bug once) to filter false positives

nelson review -m claude:sonnet

3. View confirmed findings

nelson report --verdict confirmed

أو، قم بتشغيل خط الأنابيب الكامل في أمر واحد:```bash
nelson haha --scan-model claude:haiku --scan-model claude:sonnet \
  --review-model claude:opus /path/to/project

haha تطلق عدة نماذج مسح على الكود (كل نموذج يتكرر --repeat مرات)، وتزيل التكرارات، وتحكم على كل نتيجة فريدة باستخدام نموذج مراجعة قوي واحد. تحتاج إلى نموذجين مسح على الأقل ونموذج مراجعة واحد — أسهل طريقة لوضعها في ملف إعدادات حتى تتمكن من كتابة nelson haha /path/to/project فقط. انظر وضع haha للتفاصيل.

الاستخدام

المسح

nelson scan يرسل كل ملف إلى كل نموذج مع تعليمات واسعة "ابحث عن أي ثغرة أمنية"، مشابهة لمنهج Carlini — مهمة واحدة لكل (ملف، نموذج). المعامل الرئيسي هو --repeat: حيث يشغل المصفوفة بأكملها N مرة (الافتراضي 3). التكرار، وليس الاستهداف لكل CWE، هو ما يكتشف الأخطاء فعليًا، والكشف غير موثوق بما يكفي لدرجة أن الخطأ الحقيقي يظهر غالبًا في واحدة فقط من ثلاث مرات، لذا فإن التكرار يستحق العناء حتى مع نموذج واحد. النتائج المكررة عبر المرات (وعبر النماذج) يتم دمجها عند المراجعة.```bash

Open scan with the default model (claude:haiku), repeated 3 times

nelson scan /path/to/project

A single pass, if you really want one

nelson scan --repeat 1 /path/to/project

A more capable model produces better results

nelson scan -m claude:sonnet /path/to/project

Several models at once (run in parallel, one worker each), repeated 5x

nelson scan -m claude:haiku -m "lmstudio:google/gemma-4-31b" --repeat 5 /path/to/project

**أدوات للنماذج المتوافقة مع OpenAI.** كلود كود وCLI جيميني هما بالفعل وكلاء — يقرأان أي ملفات يحتاجانها بمفردهما. نقطة نهاية مكشوفة متوافقة مع OpenAI (`openai:`, `lmstudio:`, `ollama:`) ليست كذلك: بشكل افتراضي، ترى فقط الملف الفردي الذي تم لصقه في المطالبة. مرر `--tools` لإعطاء تلك النماذج حلقة أدوات للقراءة فقط `read_file` / `grep` / `list_dir` متجذرة في الشجرة الممسوحة ضوئيًا، حتى تتمكن من تتبع الواردات والمتصلين والمساعدين إلى ملفات أخرى قبل اتخاذ قرار ما إذا كانت الثغرة الأمنية حقيقية وقابلة للوصول. (قم بتثبيت [ripgrep](https://github.com/BurntSushi/ripgrep) لأداة `grep`.) هذا يستخدم المزيد من الرموز لكل ملف. وهو لا يؤثر على مواصفات `claude:` / `gemini:`.```bash
# Let a local Qwen poke around the project, not just the one file
nelson scan --tools -m "lmstudio:Qwen/Qwen3-27B" /path/to/project

يمكنك أيضًا توجيه nelson scan إلى ملف واحد أو أكثر بدلاً من دليل كامل. هذا مفيد للفحص السريع لملف واحد، أو لمسح أي شيء يتوسع إليه glob shell. عندما تسمي الملفات بشكل صريح، يتم تخطي عوامل التصفية المعتادة القائمة على المسار (أنماط test/doc، كشف الملفات المُنشأة) — يثق Nelson في أنك تعرف ما تريد. ينطبق نفس الشيء على nelson inventory و nelson haha.```bash

Scan a single file

nelson scan path/to/suspicious.py

Scan everything a glob expands to (shell does the expansion)

nelson scan src/api/*.py

Mix and match — multiple explicit files are fine

nelson scan src/auth.py src/db.py src/handlers/*.go

Same shape works for inventory and haha

nelson inventory src/api/*.py nelson haha src/auth.py src/db.py

يمكن استئناف عمليات المسح. إذا تمت المقاطعة، فما عليك سوى الاستئناف باستخدام معرف المسح:```bash
nelson scan --resume 3

المراجعة

تمر المراجعة أولاً على إزالة التكرارات من نتائج المسح إلى مجموعات (نفس الملف و CWE، وأرقام الأسطر ضمن --line-tolerance، الافتراضي 2)، ثم ترسل ممثلًا واحدًا لكل مجموعة إلى نموذج (يفضل أن يكون أكثر ذكاءً) إلى جانب ملف المصدر الكامل، وتطلب منه تتبع تدفق التنفيذ وتقييم ما إذا كانت الثغرة قابلة للوصول وواقعية. يتم تطبيق الحكم الناتج على كل نتيجة في المجموعة، بحيث يتم الحكم على خطأ قام --repeat ونماذج متعددة بإظهاره عدة مرات مرة واحدة — لا يُدفع للمراجع مرارًا وتكرارًا عن نفس النتيجة. يتم الاحتفاظ بجميع الصفوف المكررة (مع النموذج/المرور الذي وجدها) حتى تعمل طريقة عرض المقارنة كما ينبغي.```bash

Review with Claude Sonnet (default)

nelson review

Review a specific scan

nelson review 3

Review with a different model

nelson review -m claude:opus

Widen/narrow how aggressively near-by findings are treated as one bug

nelson review --line-tolerance 5

Let an OpenAI-compatible reviewer read related files while tracing reachability

nelson review -m "lmstudio:Qwen/Qwen3-27B" --tools

تحصل كل نتيجة على حكم: `confirmed`, `false_positive`, `needs_review`، أو `resolved` (إذا تم حذف الملف منذ الفحص). تعمل علامة `--tools` بنفس الطريقة التي تعمل بها مع `nelson scan`: فهي تمنح نموذجًا متوافقًا مع OpenAI (`openai:`/`lmstudio:`/`ollama:`) حلقة `read_file`/`grep`/`list_dir` للقراءة فقط على الشجرة الممسوحة ضوئيًا، بحيث يمكنه تتبع نتيجة إلى الملفات التي تمسها قبل الحكم على قابلية الوصول إليها. إنها عملية غير فعالة بالنسبة لـ `claude:`/`gemini:`، والتي تقرأ الملفات بالفعل بمفردها. المراجعة هي عملية مُماثلة (idempotent) – تشغيلها مرة أخرى يعالج فقط النتائج غير المراجعة، لذا يمكنك المراجعة باستخدام نموذج واحد ثم تشغيل مرور ثانٍ باستخدام نموذج آخر.

### التقارير```bash
# Show all findings from the latest scan
nelson report

# Show findings from a specific scan
nelson report 3

# Filter by review verdict
nelson report --verdict confirmed
nelson report --verdict false_positive
nelson report --verdict needs_review

# Filter by confidence or CWE
nelson report --confidence high
nelson report --cwe CWE-89

# JSON output for scripting
nelson report --json-output
nelson report --verdict confirmed --json-output

مقارنة النماذج

عند المسح باستخدام نماذج متعددة (بالتوازي أو غير ذلك)، يقوم nelson compare بتجميع النتائج في مجموعات "نفس المشكلة" حتى تتمكن من رؤية حيثما اتفقت النماذج:```bash

Compare models within a single multi-model scan (default: latest)

nelson compare nelson compare 5

Compare across separate scans on the same target/commit

nelson compare --scans 3,5,7

Tighter or looser matching (default: ±2 lines)

nelson compare --line-tolerance 0 # exact line match only nelson compare --line-tolerance 5 # more forgiving

Filters

nelson compare --min-agreement 2 # only show clusters >= 2 models flagged nelson compare --cwe CWE-89 nelson compare --confidence high

JSON for scripting / your own benchmarking

nelson compare --json-output

HTML version

nelson html-compare nelson html-compare --scans 3,5,7 -o my-comparison.html

"عنقود" هو مشكلة ظاهرة واحدة: نفس الملف، نفس CWE، أرقام الأسطر ضمن نطاق التسامح. لكل عنقود، يُظهر التقرير أي النماذج أشارت إليه وأي النماذج كانت لديها فرصة للإشارة إليه ولكنها لم تفعل (مجموعة الناخبين المؤهلين هي كل نموذج أكمل مهمة فحص مفتوحة على ذلك الملف). العناقيد ذات الاتفاق العالي (مثل 3/3) هي إشارة قوية؛ عناقيد النموذج الواحد عادةً ما تكون نتائج إيجابية خاطئة. مفيد لكل من تصفية الضوضاء ومعرفة كيف يتناسب نموذج محلي صغير مقابل نموذج حدودي.

### تقارير HTML

![مثال على تقرير HTML يظهر الإجماليات والنتائج المراجعة](https://assets.kitploit.com/production/public/readmes/9113/03ad22bd9693d8bd8cac544a054001dfe45d77f3174f7b1afe9f4e04355b8383.png)

يمكن لـ Nelson إنشاء تقارير HTML ثابتة قائمة بذاتها:```bash
# Detailed report for a single scan (default: latest)
nelson html-report
nelson html-report 3
nelson html-report -o my-report.html

# Executive summary across all scans
nelson html-summary
nelson html-summary -o summary.html

يُظهر التقرير المفصل كل اكتشاف مجمعًا حسب الملف، مع شارات الثقة، وأحكام المراجعة، ومقتطفات التعليمات البرمجية، واستخدام الرموز. الملخص التنفيذي هو صفحة واحدة تظهر جميع عمليات المسح مع تعدادات المؤكد/الإيجابي الكاذب/بحاجة للمراجعة وتفصيل للاكتشافات المؤكدة لكل مسح.

أوامر أخرى```bash

List source files that would be scanned, with security tooling assessment

nelson inventory /path/to/project

(also accepts individual files or globs, just like nelson scan)

List all scans

nelson list

Show detailed status of a scan (job counts, token usage, review summary)

nelson status nelson status 3

### وضع Haha

أمر `haha` (عبارة نيلسون المميزة) يلقي بكل شيء على الكود في جولة واحدة:

1. **المسح** — كل نموذج مسح يدقق كل ملف، `--repeat` مرة لكل ملف (الافتراضي 3)
2. **إزالة التكرار** — يتم تجميع النتائج المدمجة في أخطاء فريدة
3. **المراجعة** — نموذج مراجعة قوي واحد يحكم على كل خطأ فريد مرة واحدة
4. **الملخص** — يطبع أعداد المؤكد / الإيجابيات الخاطئة / بحاجة إلى مراجعة

يتطلب **نموذجي مسح على الأقل ونموذج مراجعة واحد**. قم بتوفيرها في سطر الأوامر، أو — بشكل أكثر ملاءمة — في [ملف إعدادات](#configuration); يخرج `haha` مع خطأ إذا لم يتمكن من العثور عليها.```bash
# Models from ./nelson.yaml or ~/.nelson.yaml
nelson haha /path/to/project

# Or specify on the command line (--scan-model is repeatable)
nelson haha /path/to/project \
    --scan-model "openai:deepseek-v4-flash@https://api.deepseek.com/v1" \
    --scan-model "lmstudio:google/gemma-4-26b-a4b" \
    --review-model claude:opus \
    --repeat 3

كل شيء يظهر في فحص واحد، يمكنك فحصه لاحقًا باستخدام nelson report <scan_id> أو nelson html-report <scan_id> أو nelson compare <scan_id>.

تحذير حول استخدام الرموز: في مشروع كبير، يستهلك haha عددًا كبيرًا من الرموز ويستغرق وقتًا — فهو يشغّل وظائف فحص files × scan_models × repeat بالإضافة إلى وظيفة مراجعة واحدة لكل خطأ فريد. فكّر في تشغيل أوامر nelson scan و nelson review بشكل فردي إذا كنت تريد تحكمًا أكبر في الإيقاع والتكلفة.

الإعدادات

يقرأ Nelson ملف إعدادات اختياري بصيغة YAML حتى لا تضطر إلى إعادة كتابة نماذج المرحلة المفضلة لديك. يبحث عن ./nelson.yaml (خاص بالمشروع) ثم ~/.nelson.yaml (خاص بالمنزل)؛ ملف المشروع هو السائد لكل مفتاح، والأعلام الصريحة في سطر الأوامر تتجاوز كليهما. جميع المفاتيح اختيارية:```yaml

nelson.yaml

scan_models: # used by haha (needs >= 2) and as the default for scan

• openai:deepseek-v4-flash@https://api.deepseek.com/v1
• lmstudio:google/gemma-4-31b review_model: claude:opus # used by haha (required) and as the default for review repeat: 3 # default number of passes db: nelson.db # default database path delay: 2.0 # default per-job pacing (seconds)

مع هذا الإعداد، يعمل `nelson haha /path/to/project` بشكل مباشر، وتلتقط `nelson scan` / `nelson review` نفس الإعدادات الافتراضية ما لم تقم بتجاوزها.

## تكوين النموذج

يتم تحديد النماذج باستخدام بناء `type:model`:

| المواصف | الوصف |
|------|-------------|
| `claude:haiku` | كلود هايكو عبر CLI |
| `claude:sonnet` | كلود سونيت عبر CLI |
| `claude:opus` | كلود أوبس عبر CLI |
| `gemini:gemini-2.5-flash` | Gemini CLI مع نموذج محدد |
| `gemini:` | Gemini CLI مع النموذج الافتراضي |
| `lmstudio:google/gemma-4-26b-a4b` | LM Studio على localhost:1234 |
| `ollama:llama3` | Ollama على localhost:11434 |
| `openai:model@http://host:port/v1` | أي نقطة نهاية API متوافقة مع OpenAI (محلية أو مستضافة) |
| `openai:deepseek-v4-pro@https://api.deepseek.com/v1` | DeepSeek (مستضاف) |
| `openai:nvidia/nemotron-3-super-120b-a12b@https://openrouter.ai/api/v1` | OpenRouter (مستضاف) |

نوع `openai:` يتواصل مع أي شيء يستخدم واجهة برمجة تطبيقات المحادثات الكاملة OpenAI — خادم محلي *أو* مزود مستضاف. بالنسبة للخوادم المحلية (`lmstudio:`، `ollama:`، أو مواصف `openai:...@http://localhost...`) لا حاجة لمفتاح. بالنسبة للمزودين المستضافين، انظر [نماذج API المستضافة](#hosted-api-models-deepseek-mimo-openrouter) أدناه.

يمكن استخدام نماذج متعددة في فحص واحد لمقارنة الفعالية. افتراضيًا تعمل بالتوازي — عامل واحد لكل نموذج، نظرًا لأن حدود المعدل تكون لكل مزود:```bash
# Claude Haiku and a local Qwen model both work the queue at once
nelson scan /path/to/project \
    -m claude:haiku \
    -m "lmstudio:Qwen/Qwen3-27B"

استخدم --no-parallel إذا كنت تفضل استنزاف كل نموذج بالتسلسل (مثلًا للحفاظ على انخفاض تنافس وحدة المعالجة المركزية/وحدة معالجة الرسوميات بين نموذجين محليين على نفس الجهاز).

يتم تنظيم سرعة العوامل المستندة إلى واجهة سطر الأوامر (Claude Code, Gemini CLI) بتأخير قابل للتكوين بين المهام لتجنب الوصول إلى حدود الاشتراك المتجددة. النماذج القائمة على واجهة برمجة التطبيقات (LM Studio, Ollama, نقاط نهاية مخصصة) تعمل بدون تأخير. التأخير الافتراضي هو 2 ثانية؛ اضبط باستخدام --delay. التنظيم يكون لكل عامل، لذا كل نموذج ينتظر تأخيره الخاص بين مهامه الخاصة:```bash nelson scan /path/to/project -m claude:haiku --delay 5

### Hosted API models (DeepSeek, MiMo, OpenRouter)

لا تحتاج إلى وحدة معالجة رسومية محلية لتشغيل نموذج رخيص. أي مزود مستضاف مع نقطة نهاية متوافقة مع OpenAI يعمل من خلال مواصفة `openai:`، بالصيغة `openai:MODEL@BASE_URL` حيث ينتهي `BASE_URL` بـ `/v1`. في اختباراتي المعيارية، كانت هذه النماذج "الرخيصة" المستضافة — وخاصة DeepSeek و MiMo من Xiaomi — هي الرائدة من حيث القيمة/الأداء: فهي تعثر على معظم ما تعثر عليه النماذج الحدودية بتكلفة جزئية صغيرة، مما يجعلها مناسبة تمامًا لأسلوب Nelson القائم على القوة الغاشمة وفحص كل ملف.

**المصادقة.** يقرأ Nelson المفتاح من متغير البيئة `OPENAI_API_KEY` (الاتفاقية العالمية المتوافقة مع OpenAI). قم بتصدير مفتاح مزودك تحت هذا الاسم قبل المسح — أيًا كان المزود الذي يشير إليه `@BASE_URL`:```bash
export OPENAI_API_KEY="sk-your-provider-key"

الحفاظ على المفتاح في البيئة (أو ملف .env غير متتبع تقوم بتشغيله بـ source) يبقيه خارج محفوظات الصدفة وخارج أي ملف يكتبه Nelson. ظهور مفتاح مفقود أو مرفوض يعبر عن فشل في المصادقة، وليس كرسالة صامتة "تم المسح ولم يُعثر على شيء."

DeepSeek — deepseek-v4-pro هو النموذج الأقوى/الأغلى ثمنًا، بينما deepseek-v4-flash هو الأرخص:```bash export OPENAI_API_KEY="sk-..." # your DeepSeek key

nelson scan /path/to/project -m "openai:deepseek-v4-pro@https://api.deepseek.com/v1"

Cheaper, still surprisingly capable

nelson scan /path/to/project -m "openai:deepseek-v4-flash@https://api.deepseek.com/v1"

**MiMo (Xiaomi)** — أشر إلى نقطة نهاية MiMo المتوافقة مع OpenAI:```bash
export OPENAI_API_KEY="..."      # your MiMo key

nelson scan /path/to/project \
    -m "openai:mimo-v2.5-pro@https://token-plan-sgp.xiaomimimo.com/v1"

OpenRouter — مفتاح واحد وعنوان URL أساسي واحد يصلان إلى معظم النماذج الرئيسية من خلال حساب واحد؛ معرف النموذج هو slug مسبوق بمزود الخدمة من كتالوج OpenRouter (مثل nvidia/nemotron-3-super-120b-a12b، أضف :free للحصول على مسار الطبقة المجانية). هذه طريقة ملائمة لتجربة العديد من النماذج دون التسجيل لدى كل مزود.```bash export OPENAI_API_KEY="sk-or-..." # your OpenRouter key

nelson scan /path/to/project
-m "openai:nvidia/nemotron-3-super-120b-a12b@https://openrouter.ai/api/v1"

افتراضيًا، نموذج `openai:` المستضاف هو **لقطة واحدة** — فهو يرى فقط الملف الواحد
الملصق في كل موجه. أضف `--tools` (انظر [فحص](#scanning)) لمنحه
حلقة قراءة فقط من `read_file`/`grep`/`list_dir` عبر المشروع بحيث يمكنه متابعة
عمليات الاستيراد ومواقع الاستدعاء إلى ملفات أخرى قبل أن يقرر ما إذا كان الاكتشاف حقيقيًا. هذا
يكلف رموزًا أكثر لكنه يميل إلى تقليل الإيجابيات الخاطئة:```bash
nelson scan --tools /path/to/project \
    -m "openai:deepseek-v4-pro@https://api.deepseek.com/v1"

نفس المواصفات و OPENAI_API_KEY تعمل مع nelson review — نموذج مستضاف رخيص يمكنه المسح ونموذج أقوى يمكنه المراجعة، أو العكس:```bash nelson review -m "openai:deepseek-v4-pro@https://api.deepseek.com/v1" --tools

نظرًا لأن حدود المعدل تكون لكل مزود، يمكنك مزج نموذج مستضاف مع نموذج محلي (أو Claude/Gemini) في مسح واحد، ويقوم Nelson بتشغيل عامل واحد لكل نموذج بالتوازي:```bash
nelson scan /path/to/project \
    -m "openai:deepseek-v4-flash@https://api.deepseek.com/v1" \
    -m "lmstudio:Qwen/Qwen3-27B" \
    -m claude:haiku

المطالبات

تطلب مطالبة المسح من النموذج العثور على أي شيء في ملف واحد، مطالبة واحدة لكل مهمة (ملف، نموذج) (ويتم تكرار المصفوفة بالكامل --repeat مرة):``` You are a security researcher performing a vulnerability audit. Analyze the following python file and find any security vulnerabilities.

Look for all classes of vulnerability including but not limited to:

• Injection attacks (SQL, command, code, XSS, etc.)
• Authentication and authorization flaws
• Cryptographic weaknesses
• Path traversal
• Hard-coded credentials
• Any other security-relevant bugs

IMPORTANT INSTRUCTIONS:

• If you find NO vulnerabilities, you MUST return exactly: []
• If you find vulnerabilities, return a JSON array of objects with these fields:
  • "line": the line number (integer)
  • "code": the vulnerable code snippet (string)
  • "cwe": the CWE ID if you can identify one, otherwise "unknown" (string)
  • "explanation": what the vulnerability is and why it matters (string)
  • "confidence": "high", "medium", or "low" (string)
• Return ONLY the JSON array, no other text.
• Rank by severity — put the most serious vulnerability first.

File: app/db.py

يحدد النموذج CWE نفسه؛ يسجله Nelson بجانب الاكتشاف ويستخدمه (بالإضافة إلى رقم السطر) لتجميع التقارير المكررة أثناء المراجعة. تستخدم مرحلة المراجعة موجهًا منفصلاً يقدم للمراجع الملف الكامل والاكتشاف المُبلغ عنه ويطلب منه تتبع إمكانية الوصول والحكم بـ `confirmed` / `false_positive` / `needs_review`.

## تصفية الملفات

يستبعد Nelson تلقائيًا الملفات التي من غير المحتمل أن تحتوي على ثغرات إنتاجية:

- **كود الاختبار**: `test_*`, `*_test.*`, `*_spec.*`, `tests/`, `__tests__/`, إلخ.
- **التوثيق**: `docs/`, `*.md`, `*.txt`
- **الكود المُنشأ**: الملفات التي تحتوي على رؤوس "DO NOT EDIT" / "AUTO-GENERATED"
- **الكود المُورّد**: `vendor/`, `node_modules/`, `third_party/`
- **الملفات الكبيرة**: أكثر من 500 كيلوبايت
- **الملفات غير المصدرية**: يفحص فقط الملفات ذات الامتدادات المعروفة (`.py`, `.go`, `.ts`, `.js`, `.c`, `.cpp`, `.rs`, `.java`, `.rb`, `.php`, `.pl`, `.pm`, `.sh`)

استخدم `nelson inventory /path/to/project` لمعرفة بالضبط الملفات التي سيتم فحصها.

تنطبق عوامل التصفية هذه فقط عند فحص دليل. إذا قمت بتسمية الملفات صراحةً في سطر الأوامر (على سبيل المثال `nelson scan src/foo.py src/bar.py`)، يتم تطبيق فحوصات الامتداد والحجم فقط — يتم تخطي اكتشاف ملفات الاختبار/التوثيق/الكود المُنشأ، على افتراض أنك تقصد ما كتبته.

## تقييم أدوات الأمان

يتحقق Nelson مما إذا كان مشروعك يستخدم أدوات التحليل الثابت الموصى بها ويبلغ عن الفجوات. يتم تشغيل هذا تلقائيًا كجزء من `nelson inventory` و `nelson report`. على سبيل المثال، سيُعلم إذا كان:

- Ruff موجود ولكن قواعد الأمان S (Bandit) غير مفعلة
- مشروع Go ليس لديه golangci-lint مع gosec
- مشروع TypeScript ليس لديه eslint-plugin-security
- مشروع Perl ليس لديه تهيئة Perl::Critic

الفكرة هي أن أدوات التحليل الثابت أرخص وأسرع من الذكاء الاصطناعي لمطابقة أنماط الثغرات، ويجب أن يكملها Nelson بدلاً من تكرار عملها.

## قاعدة البيانات

يتم تخزين حالة المسح في قاعدة بيانات SQLite (`nelson.db` في الدليل الحالي افتراضيًا). استخدم `--db` لتحديد مسار مختلف.

يتم الاحتفاظ بجميع نتائج المسح والاكتشافات وأحكام المراجعة، مما يسهل مقارنة النتائج عبر النماذج والأنماط والوقت.

## تتبع الرموز

يتتبع Nelson استخدام الرموز والتكلفة لكل مهمة. استخدم `nelson status` لرؤية الإجماليات.