TDO स्टैंडअलोन एक्सट्रैक्टर

एक शक्तिशाली, स्टैंडअलोन कमांड-लाइन टूल जो उन्नत संरचित आउटपुट क्षमताओं वाले बड़े भाषा मॉडल (LLM) का उपयोग करके दस्तावेज़ों से साइबर खतरा खुफिया (CTI) निकालने के लिए है।

🚀 विशेषताएँ

• बहु-प्रारूप दस्तावेज़ समर्थन: PDF, DOCX, TXT, और मार्कडाउन फ़ाइलें
• उन्नत LLM एकीकरण: संरचित आउटपुट और स्वचालित फ़ॉलबैक पार्सिंग के साथ Google Gemini मॉडल
• व्यापक CTI स्कीमा: 12 इकाई प्रकार और 24 संबंध प्रकार समृद्ध गुणों सहित
• पहचान अवसर निर्माण: साक्ष्य-समर्थित कार्रवाई योग्य खतरा पहचान नियम बनाता है
• हमला प्रवाह संश्लेषण: साक्ष्य-आधारित MITRE ATT&CK प्रवाह आरेख उत्पन्न करता है
• संरचित आउटपुट विश्वसनीयता: 100% JSON पार्सिंग सफलता दर के साथ Pydantic स्कीमा
• समानांतर प्रसंस्करण: प्रगति ट्रैकिंग के साथ एक साथ कई फ़ाइलें प्रोसेस करें
• पोर्टेबल और सेल्फ-कंटेन्ड: पर्यावरण-आधारित कॉन्फ़िगरेशन के साथ न्यूनतम निर्भरताएँ

📋 त्वरित प्रारंभ

1. स्थापना

# Clone या standalone-tdo फ़ोल्डर डाउनलोड करें
cd standalone-tdo

# वर्चुअल वातावरण बनाएँ (अनुशंसित)
python -m venv .venv
source .venv/bin/activate  # Windows पर: .venv\Scripts\activate

# निर्भरताएँ स्थापित करें
pip install -r requirements.txt

2. कॉन्फ़िगरेशन

टूल कॉन्फ़िगरेशन के लिए .env फ़ाइल से लोड किए गए पर्यावरण चर का उपयोग करता है:

# उदाहरण कॉन्फ़िगरेशन कॉपी करें
cp env.example .env

# अपनी सेटिंग्स के साथ .env संपादित करें
# आवश्यक चर:
GEMINI_API_KEY=your-google-ai-api-key-here
GEMINI_MODEL=gemini-2.5-flash

Gemini API कुंजी प्राप्त करना:

1. Google AI Studio पर जाएँ
2. एक नई API कुंजी बनाएँ
3. कुंजी को अपनी .env फ़ाइल में कॉपी करें

उपलब्ध मॉडल:

• gemini-2.5-flash-preview-05-20 (अनुशंसित - तेज़ और लागत प्रभावी)
• gemini-2.5-pro-preview-06-05 (अधिक शक्तिशाली, धीमा)

3. मूल उपयोग

# सभी सुविधाओं के साथ एक फ़ाइल प्रोसेस करें
python tdo_bulk.py report.pdf --flow --opps

# कई फ़ाइलें प्रोसेस करें
python tdo_bulk.py file1.pdf file2.docx file3.txt

# समानांतर कार्यकर्ताओं के साथ एक निर्देशिका में सभी फ़ाइलें प्रोसेस करें
python tdo_bulk.py reports/ -j 4

# मूल्यांकन के साथ व्यापक विश्लेषण उत्पन्न करें
python tdo_bulk.py report.pdf --flow --opps --eval-opps

🎯 कमांड लाइन संदर्भ

usage: tdo_bulk.py [options] FILE [FILE ...]

Positional Arguments:
  FILE                  प्रोसेस करने के लिए एक या अधिक फ़ाइलें या निर्देशिकाएँ

Core Options:
  -o, --output DIR      आउटपुट निर्देशिका (डिफ़ॉल्ट: ./extracted_data)
  --csv FILE            CSV फ़ाइल में सारांश निर्यात करें
  -j, --jobs N          समानांतर कार्यकर्ताओं की संख्या (डिफ़ॉल्ट: 1)
  --retries N           LLM पुनर्प्रयास संख्या (डिफ़ॉल्ट: 2)
  --backoff SEC         घातांकीय बैक-ऑफ़ आधार (डिफ़ॉल्ट: 1.5)

Analysis Features:
  --flow                Attack-Flow JSON उत्पन्न करें
  --opps                खतरा पहचान अवसर उत्पन्न करें
  --eval-opps           पहचान अवसरों की गुणवत्ता का मूल्यांकन करें
  --debug-opps          अवसर निर्माण के लिए डीबग जानकारी दिखाएँ

Output Control:
  -q, --quiet           न्यूनतम कंसोल आउटपुट
  -v, --verbose         डीबग-स्तरीय लॉगिंग
  -h, --help            सहायता संदेश दिखाएँ और बाहर निकलें

उदाहरण कमांड

# बुनियादी CTI निष्कर्षण
python tdo_bulk.py threat_report.pdf

# सभी सुविधाओं के साथ पूर्ण विश्लेषण
python tdo_bulk.py apt_report.pdf --flow --opps --eval-opps

# समानांतर कार्यकर्ताओं के साथ बैच प्रसंस्करण
python tdo_bulk.py reports_folder/ -j 8 --flow --opps

# परिणाम CSV में निर्यात करें
python tdo_bulk.py *.pdf --csv results.csv

# ऑटोमेशन के लिए शांत मोड
python tdo_bulk.py reports/ -q -o /var/soc/cti --opps

📊 आउटपुट फ़ाइलें

प्रत्येक प्रोसेस की गई फ़ाइल के लिए, टूल उत्पन्न करता है:

प्राथमिक आउटपुट

• {filename}_extracted.json: व्यापक स्कीमा के साथ संरचित CTI डेटा
• {filename}_{timestamp}.md: सभी विश्लेषण के साथ मानव-पठनीय मार्कडाउन रिपोर्ट

वैकल्पिक आउटपुट (फ़्लैग के साथ)

• Attack Flow JSON: साक्ष्य-आधारित MITRE ATT&CK प्रवाह संरचना (--flow के साथ)
• Detection Opportunities: साक्ष्य के साथ कार्रवाई योग्य पहचान नियम (--opps के साथ)

🔍 CTI स्कीमा अवलोकन

इकाई प्रकार (12 प्रकार)

संबंध प्रकार (24 प्रकार)

आरोपण और अभिनेता संबंध:

• USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS

तकनीकी संबंध:

• TOOL_IMPLEMENTS_TECHNIQUE, HOSTS_ON, COMMUNICATES_WITH, VARIANT_OF
• DROPS, DOWNLOADS, INDICATES, OBSERVED_ON, EXPLOITS

उन्नत संबंध:

• MITIGATES, DETECTS, IS_SUBTECHNIQUE_OF, FLOW_CONTAINS_STEP
• FLOW_USED_BY_ACTOR, OBSERVES, SOURCED_FROM

सभी संबंध confidence, source, first_seen, last_seen जैसे गुणों का समर्थन करते हैं।

💡 पहचान अवसर

टूल साक्ष्य-आधारित पहचान अवसर उत्पन्न करता है:

मुख्य विशेषताएँ

• तकनीक मैपिंग: विशिष्ट MITRE ATT&CK तकनीकों से लिंक
• अवलोकनीय कलाकृतियाँ: पहचानने के लिए विशिष्ट संकेतक
• व्यवहारिक पैटर्न: निगरानी के लिए अनुक्रम और पैटर्न
• साक्ष्य उद्धरण: स्रोत रिपोर्टों से सीधे उद्धरण
• विश्वास स्कोर: विश्वसनीयता आकलन (0.0-1.0)
• गुणवत्ता मूल्यांकन: मानदंड विभाजन के साथ स्वचालित स्कोरिंग

उदाहरण आउटपुट

{
  "id": "opp-001",
  "name": "पावरशेल प्रक्रिया इंजेक्शन का पता लगाएं",
  "technique_id": "T1055",
  "artefacts": ["WriteProcessMemory कॉल के साथ powershell.exe"],
  "behaviours": ["वैध प्रक्रियाओं में प्रक्रिया इंजेक्शन"],
  "rationale": "APT समूह आमतौर पर प्रक्रिया इंजेक्शन के लिए पावरशेल का उपयोग करते हैं",
  "confidence": 0.8,
  "source": "प्रक्रिया इंजेक्शन के लिए पावरशेल का उपयोग (T1055)",
  "evidence": [
    "• पावरशेल WriteProcessMemory कॉल निष्पादित करता है (पंक्ति 45)",
    "• संबंध: ThreatActor USES_TECHNIQUE T1055"
  ]
}

🔗 हमला प्रवाह संश्लेषण

उन्नत हमला प्रवाह प्रदान करता है:

• साक्ष्य-आधारित क्रम: लौकिक और कारण साक्ष्य द्वारा समर्थित चरण
• इकाई संदर्भ: प्रत्येक चरण निकाले गए CTI इकाइयों को संदर्भित करता है
• स्पष्ट तर्क: उद्धरणों के साथ चरण क्रम के लिए औचित्य
• व्यापक कवरेज: पूर्ण हमले के जीवनचक्र को कवर करने वाले 25 चरण तक

उदाहरण हमला प्रवाह

{
  "flow": {
    "label": "AttackFlow",
    "pk": "attack-flow--uuid",
    "properties": {
      "name": "APT29 बहु-चरणीय हमला",
      "description": "डेटा निष्कासन प्रवाह के लिए परिष्कृत फ़िशिंग"
    }
  },
  "steps": [
    {
      "order": 1,
      "entity": {"label": "Technique", "pk": "T1566.001"},
      "description": "फ़िशिंग अटैचमेंट वितरण",
      "reason": "रिपोर्ट के अनुभाग 2.1 में उल्लिखित प्रारंभिक पहुँच विधि"
    }
  ]
}

🏗️ आर्किटेक्चर अवलोकन

मुख्य घटक

🎯 मुख्य CLI (tdo_bulk.py)

• तर्क पार्सिंग और पर्यावरण सत्यापन के साथ प्रवेश बिंदु
• python-dotenv का उपयोग करके .env कॉन्फ़िगरेशन लोड करता है
• प्रगति ट्रैकिंग के साथ बल्क प्रसंस्करण का आयोजन करता है

⚙️ बल्क रनर (tdo_bulk_runner.py)

• ThreadPoolExecutor के साथ समानांतर प्रसंस्करण प्रबंधित करता है
• निष्कर्षण पाइपलाइन चरणों का समन्वय करता है
• प्रगति कॉलबैक और त्रुटि पुनर्प्राप्ति को संभालता है

🧠 CTI एक्सट्रैक्टर (tdo_core/extractors/report_processor.py)

• दस्तावेज़ पार्सिंग: बहु-प्रारूप समर्थन (PDF, DOCX, TXT, MD)
• LLM एकीकरण: संरचित आउटपुट के साथ Google Gemini
• फ़ॉलबैक पार्सिंग: जब संरचित आउटपुट विफल होता है तो मैन्युअल JSON पार्सिंग
• टोकन प्रबंधन: बड़े दस्तावेज़ों के लिए स्वचालित चंकिंग
• स्कीमा सत्यापन: Pydantic मॉडल डेटा स्थिरता सुनिश्चित करते हैं

🔍 TDO जनरेटर (tdo_core/detection/opportunity_generator.py)

• साक्ष्य-आधारित पहचान अवसर निर्माण
• MITRE ATT&CK तकनीक मैपिंग
• स्कोरिंग मानदंड के साथ गुणवत्ता मूल्यांकन
• विस्तृत विश्लेषण के लिए डीबग मोड

🌊 हमला प्रवाह संश्लेषक (tdo_core/flows/attack_flow_synthesizer.py)

• साक्ष्य समर्थन के साथ LLM-संचालित प्रवाह निर्माण
• सरल प्रवाहों के लिए नियम-आधारित फ़ॉलबैक
• स्पष्ट तर्क के साथ चरण क्रम
• इकाई संबंध विश्लेषण

📝 रिपोर्ट जनरेटर (tdo_core/report/md_export.py)

• मानव-पठनीय मार्कडाउन रिपोर्ट निर्माण
• संरचित डेटा प्रस्तुति
• सभी विश्लेषण घटकों का एकीकरण

🎨 प्रॉम्प्ट प्रबंधन (tdo_core/llm/prompts.py)

• केंद्रीकृत प्रॉम्प्ट टेम्पलेट
• संरचित आउटपुट अनुकूलन
• LLM इंटरैक्शन के लिए सर्वोत्तम अभ्यास

डेटा प्रवाह

दस्तावेज़ इनपुट → पाठ निष्कर्षण → एलएलएम प्रसंस्करण → संरचित आउटपुट
     ↓              ↓                 ↓               ↓
   PDF/DOCX      स्वच्छ पाठ     Gemini API     JSON + फ़ॉलबैक
     ↓              ↓                 ↓               ↓
 बहु-प्रारूप   पूर्व-प्रसंस्करण  Pydantic स्कीमा  सत्यापन
     ↓              ↓                 ↓               ↓
फ़ाइल समर्थन   पाठ सफाई        संरचित डेटा   CTI ग्राफ़
                                      ↓
                              पोस्ट-प्रसंस्करण
                                 ↓         ↓
                          हमला प्रवाह  पहचान अवसर
                                 ↓         ↓
                            मार्कडाउन रिपोर्ट निर्यात

🛠️ उन्नत कॉन्फ़िगरेशन

पर्यावरण चर

मॉडल चयन गाइड

🔧 समस्या निवारण

सामान्य समस्याएँ

लापता पर्यावरण चर

Error: Required environment variables missing: GEMINI_API_KEY, GEMINI_MODEL

समाधान: दोनों आवश्यक चरों के साथ .env फ़ाइल बनाएँ

असमर्थित फ़ाइल प्रारूप

Skipping unsupported file: document.rtf

समाधान: PDF, DOCX, TXT, या MD प्रारूप में बदलें

LLM प्रसंस्करण त्रुटियाँ

Structured Gemini API error: ...

समाधान:

• API कुंजी की वैधता जाँचें
• मॉडल नाम की वर्तनी सत्यापित करें
• पहले छोटे दस्तावेज़ों के साथ प्रयास करें
• विस्तृत त्रुटि लॉग के लिए --verbose का उपयोग करें

JSON पार्सिंग समस्याएँ

टूल स्वचालित रूप से JSON पार्सिंग समस्याओं को संभालता है:

• प्राथमिक विधि के रूप में संरचित आउटपुट
• मैन्युअल पार्सिंग फ़ॉलबैक
• काटे गए प्रतिक्रियाओं के लिए JSON मरम्मत
• सुगम त्रुटि पुनर्प्राप्ति

प्रदर्शन अनुकूलन

• समानांतर प्रसंस्करण: कई फ़ाइलों के लिए -j फ़्लैग का उपयोग करें
• मॉडल चयन: बल्क प्रसंस्करण के लिए तेज़ मॉडल का उपयोग करें
• शांत मोड: ऑटोमेशन स्क्रिप्ट के लिए -q का उपयोग करें
• आउटपुट प्रबंधन: कस्टम आउटपुट निर्देशिकाओं के साथ व्यवस्थित करें

डीबग मोड

# वर्बोज़ लॉगिंग सक्षम करें
python tdo_bulk.py report.pdf -v

# पहचान अवसरों को डीबग करें
python tdo_bulk.py report.pdf --opps --debug-opps

# विस्तृत लॉग निर्यात करें
python tdo_bulk.py report.pdf -v > processing.log 2>&1

📦 निर्भरताएँ

टूल को Python 3.9+ और इन प्रमुख पैकेजों की आवश्यकता है:

• google-generativeai: संरचित आउटपुट के साथ Google AI (Gemini) API क्लाइंट
• PyMuPDF: उच्च-प्रदर्शन PDF पाठ निष्कर्षण
• python-docx: माइक्रोसॉफ्ट वर्ड दस्तावेज़ प्रसंस्करण
• pandas: डेटा हेरफेर और CSV निर्यात
• pydantic: स्कीमा सत्यापन और संरचित आउटपुट
• python-dotenv: पर्यावरण चर प्रबंधन
• cleantext: पाठ पूर्व-प्रसंस्करण उपयोगिताएँ

🚧 सीमाएँ

यह स्टैंडअलोन संस्करण:

• नॉलेज ग्राफ़ या Neo4j एकीकरण शामिल नहीं करता
• समानता खोज के लिए वेक्टर डेटाबेस सुविधाओं का समर्थन नहीं करता
• कोई रीयल-टाइम पुनर्प्राप्ति संवर्धन क्षमता नहीं
• पूर्ण TDO प्लेटफ़ॉर्म की तुलना में सरलीकृत

हालाँकि, इसमें अधिकांश उपयोग मामलों के लिए आवश्यक सभी मुख्य CTI निष्कर्षण और विश्लेषण क्षमताएँ शामिल हैं।

🔄 हाल के संवर्द्धन

• पर्यावरण कॉन्फ़िगरेशन: dotenv के साथ .env फ़ाइल प्रबंधन में स्थानांतरित
• संरचित आउटपुट: Google Gemini संरचित आउटपुट के साथ 100% विश्वसनीय JSON पार्सिंग
• उन्नत स्कीमा: व्यापक 12 इकाई प्रकार और 24 संबंध प्रकार
• पहचान अवसर: मूल्यांकन के साथ साक्ष्य-आधारित पहचान नियम निर्माण
• हमला प्रवाह सुधार: साक्ष्य समर्थन और स्पष्ट तर्क के साथ उन्नत
• कोई हार्डकोडेड डिफ़ॉल्ट नहीं: सभी कॉन्फ़िगरेशन पर्यावरण चर से आता है
• मजबूत त्रुटि प्रबंधन: स्वचालित फ़ॉलबैक पार्सिंग और सुगम त्रुटि पुनर्प्राप्ति

🔒 सुरक्षा विचार

API कुंजी सुरक्षा

• अपनी .env फ़ाइल कभी भी commit न करें - यह .gitignore द्वारा बाहर रखी गई है
• GEMINI_API_KEY को पर्यावरण चर का उपयोग करके सुरक्षित रूप से संग्रहीत करें
• समय-समय पर API कुंजियाँ बदलें
• विस्तृत सुरक्षा मार्गदर्शन के लिए SECURITY.md देखें

डेटा गोपनीयता

• दस्तावेज़ पाठ प्रसंस्करण के लिए Google के Gemini API को भेजा जाता है
• संवेदनशील दस्तावेज़ों को प्रोसेस करने से पहले Google की AI डेटा उपयोग नीतियों की समीक्षा करें
• निकाले गए डेटा में संवेदनशील जानकारी (IOCs, संगठन के नाम, फ़ाइल पथ) हो सकती है
• अपने संगठन के बाहर साझा करने से पहले आउटपुट की समीक्षा करें

आउटपुट डेटा

निकाली गई JSON और मार्कडाउन फ़ाइलों में शामिल हो सकता है:

• IP पते और डोमेन नाम (बुनियादी ढाँचा संकेतक)
• फ़ाइल हैश और तकनीकी संकेतक
• संगठन और लक्ष्य जानकारी
• विस्तृत खतरा अभिनेता और अभियान डेटा

सार्वजनिक रूप से साझा करने से पहले हमेशा आउटपुट की समीक्षा करें।

सुरक्षा समस्याओं की रिपोर्ट करना

कृपया सुरक्षा कमजोरियों की जिम्मेदारीपूर्वक रिपोर्ट करें। विवरण के लिए SECURITY.md देखें।

📄 लाइसेंस

यह प्रोजेक्ट MIT लाइसेंस के तहत लाइसेंस प्राप्त है - विवरण के लिए LICENSE देखें।

🤝 योगदान

योगदान का स्वागत है! दिशानिर्देशों के लिए कृपया CONTRIBUTING.md पढ़ें।

सहायता चाहिए? त्वरित संदर्भ के लिए python tdo_bulk.py --help चलाएँ या ऊपर समस्या निवारण अनुभाग देखें।