{"id":30208593,"url":"https://github.com/fikriaf/sentrysol-langchain","last_synced_at":"2025-10-19T23:05:22.589Z","repository":{"id":309181841,"uuid":"1034203513","full_name":"fikriaf/SentrySol-Langchain","owner":"fikriaf","description":"Adaptive Web3 Security Intelligence Pipeline • Multi-Agent • LLM Scoring • Real-Time Wallet \u0026 Transaction Risk Profiling","archived":false,"fork":false,"pushed_at":"2025-08-10T10:16:34.000Z","size":630,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T12:22:46.655Z","etag":null,"topics":["ai-agents","intelligence","langchain","security","web3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fikriaf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T02:51:26.000Z","updated_at":"2025-08-10T10:16:37.000Z","dependencies_parsed_at":"2025-08-10T12:22:48.582Z","dependency_job_id":"490fa341-d714-4685-b062-28b58b7d1e22","html_url":"https://github.com/fikriaf/SentrySol-Langchain","commit_stats":null,"previous_names":["fikriaf/sentrysol-langchain"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fikriaf/SentrySol-Langchain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fikriaf%2FSentrySol-Langchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fikriaf%2FSentrySol-Langchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fikriaf%2FSentrySol-Langchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fikriaf%2FSentrySol-Langchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fikriaf","download_url":"https://codeload.github.com/fikriaf/SentrySol-Langchain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fikriaf%2FSentrySol-Langchain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270467643,"owners_count":24588806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","intelligence","langchain","security","web3"],"created_at":"2025-08-13T18:01:25.156Z","updated_at":"2025-10-19T23:05:22.512Z","avatar_url":"https://github.com/fikriaf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eSentrySol-Langchain\u003c/h1\u003e\n\n\u003c!-- BADGES --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Python\" src=\"https://img.shields.io/badge/Python-3.10+-3776AB?logo=python\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"FastAPI\" src=\"https://img.shields.io/badge/FastAPI-Backend-009688?logo=fastapi\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"LangChain\" src=\"https://img.shields.io/badge/LangChain-Orchestration-1E88E5\"\u003e\n  \u003cimg alt=\"Mistral\" src=\"https://img.shields.io/badge/LLM-Mistral%20Medium-FF6F00\"\u003e\n  \u003cimg alt=\"Solana\" src=\"https://img.shields.io/badge/Solana-Supported-9945FF?logo=solana\"\u003e\n  \u003cimg alt=\"Agent Mode\" src=\"https://img.shields.io/badge/Agent%20Mode-Direct%20/%20Reasoning-673AB7\"\u003e\n  \u003cimg alt=\"Security Scoring\" src=\"https://img.shields.io/badge/Security%20Scoring-LLM%20Driven-4CAF50\"\u003e\n  \u003cimg alt=\"Status\" src=\"https://img.shields.io/badge/Status-Active-success\"\u003e\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/License-Private-red\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eAdaptive Web3 Security Intelligence Pipeline • Multi-Agent • LLM Scoring • Real-Time Wallet \u0026 Transaction Risk Profiling\u003c/b\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#1-ringkasan-fitur\"\u003eFitur\u003c/a\u003e •\n  \u003ca href=\"#2-arsitektur-tingkat-tinggi\"\u003eArsitektur\u003c/a\u003e •\n  \u003ca href=\"#8-endpoints\"\u003eAPI\u003c/a\u003e •\n  \u003ca href=\"#7-skor--risiko\"\u003eScoring\u003c/a\u003e •\n  \u003ca href=\"#11-konfigurasi--variabel-lingkungan-disarankan\"\u003eKonfigurasi\u003c/a\u003e •\n  \u003ca href=\"#13-ekstensi--kustomisasi\"\u003eEkstensi\u003c/a\u003e •\n  \u003ca href=\"#17-roadmap-saran\"\u003eRoadmap\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\nPlatform analisis keamanan Web3 (fokus Solana \u0026 multi-chain) yang memanfaatkan FastAPI + LangChain + multi-agent + LLM (Mistral) untuk:\n- Screening wallet \u0026 token\n- Tracing transaksi \u0026 histori\n- Ekstraksi label / domain (Helius)\n- Evaluasi risiko terstruktur + skor keamanan + rekomendasi eksekutif\n\n## 1. Ringkasan Fitur\n- Mode eksekusi ganda: Direct Tool Execution (deterministik) atau Agent-Based (reasoning).\n- Multi-tool orchestrator (Supervisor) dengan scoring berbasis LLM.\n- Dynamic \"WHAT / WHO / HOW\" summary.\n- Security scores (overall + wallet + transaction + token + domain).\n- Risk level mapping (VERY_LOW → CRITICAL).\n- Pre-transaction screening \u0026 wallet-only API.\n- Batch-ready (function `run_supervisor_batch`).\n\n## 2. Arsitektur Tingkat Tinggi\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                        Client / UI                       │\n└───────────────┬──────────────────────────────────────────┘\n                │ HTTP (JSON)\n        ┌───────▼────────┐\n        │   FastAPI       │ main.py\n        │  (Routing)      │\n        └───┬─────────────┘\n            │ panggil analyze()/tools\n            ▼\n   ┌──────────────────────────┐\n   │ Supervisor Orchestrator  │ supervisor.py\n   │ - Input detection         │\n   │ - Mode switch             │\n   │ - Tool calling / agent    │\n   │ - Dynamic summary         │\n   │ - LLM scoring / recs      │\n   └──────────┬───────────────┘\n              │\n   ┌──────────▼───────────┐\n   │   Agents / Tools      │ agents.py\n   │  - Chainabuse (token) │\n   │  - Metasleuth (wallet)│\n   │  - Helius (tx, labels)│\n   │  - Mistral FT (ML)    │\n   └──────────┬───────────┘\n              │ data mentah\n              ▼\n        ┌──────────────┐\n        │  LLM (Mistral)│\n        │  - Scoring    │\n        │  - Summaries  │\n        └───────────────┘\n```\n\n## 3. Komponen Utama\n- main.py: Endpoint FastAPI (/analyze, /pre-transaction, /check-wallet, /transactions, /transfers, /domains, /labels).\n- agents.py: Definisi tool wrapper API eksternal.\n- supervisor.py: Orkestrasi pipeline end-to-end + scoring + fallback.\n- README.md: Dokumentasi.\n- (Log) app.log, supervisor.log, agents.log.\n\n## 4. Mode Eksekusi\n1. direct_tool_execution = true  \n   - Memanggil tool secara langsung (urutan deterministik).\n   - Cepat, stabil, output konsisten.\n\n2. direct_tool_execution = false  \n   - Menggunakan LangChain agent (zero-shot-react-description).\n   - Reasoning fleksibel, bisa variasi output.\n   - Lebih rentan error parsing → fallback disiapkan.\n\n## 5. Alur Eksekusi (Direct)\n```\nRequest JSON\n  ↓\nValidasi + detect input_type (wallet / token / tx)\n  ↓\nTool Invocation (wallet → labels → tx → transfers → ML)\n  ↓\nLLM Summary (WHAT/WHO/HOW)\n  ↓\nLLM Security Scoring (JSON parsed)\n  ↓\nGenerate Recommendations + Executive Summary\n  ↓\nResponse final (analysis + meta)\n```\n\n## 6. Input Detection\nHeuristik:\n- token_address → token_analysis\n- wallet_address → wallet_analysis\n- transaction_hash / transaction_details → transaction_analysis\n- lainnya → general_analysis\n\n## 7. Skor \u0026 Risiko\nField:\n- overall_security_score\n- wallet_security_score\n- transaction_security_score\n- token_security_score\n- domain_security_score\n- confidence_level\n- risk_level (VERY_LOW, LOW, MODERATE, HIGH, CRITICAL)\n- positive_indicators / threat_indicators\n- compliance_score / reputation_score\n\nInterpretasi singkat:\n- 90–100 = Sangat aman (VERY_LOW)\n- 75–89 = Aman (LOW)\n- 60–74 = Waspada (MODERATE)\n- 40–59 = Risiko tinggi (HIGH)\n- 0–39  = Sangat berbahaya (CRITICAL)\n\n## 8. Endpoints\n\n| Endpoint | Method | Deskripsi |\n|----------|--------|-----------|\n| /analyze | POST | Analisis umum (wallet/tx/token kombinasi) |\n| /pre-transaction | POST | Screening sebelum eksekusi transaksi |\n| /check-wallet | GET | Fokus analisa wallet saja |\n| /transactions | GET | Raw histori transaksi (Helius) |\n| /transfers | GET | Token transfers (spam / scam indicator) |\n| /domains | GET | Domain / SNS |\n| /labels | GET | Label reputasi (Helius) |\n\nQuery param penting:\n- direct_tool_execution=true/false\n\n## 9. Endpoint /analyze\nRequest:\n```json\n{\n  \"data\": {\n    \"wallet_address\": \"DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6zDvNrjggrE3wTBas\",\n    \"transaction_hash\": \"ExampleTxHashOrSignatureHere\",\n    \"transaction_details\": \"From: ...\\nTo: ...\\nValue: 0.01 SOL\",\n    \"chain\": \"solana\",\n    \"direct_tool_execution\": true\n  }\n}\n```\n\nRespons (dipersingkat):\n```json\n{\n  \"status\": \"success\",\n  \"analysis\": {\n    \"wallet_screening\": \"...\",\n    \"transaction_details\": \"...\",\n    \"labels_and_domains\": \"...\",\n    \"token_transfers\": \"...\",\n    \"security_scores\": {\n      \"overall_security_score\": 82,\n      \"risk_level\": \"LOW\",\n      \"confidence_level\": 78\n    },\n    \"professional_summary\": {\n      \"executive_summary\": \"...\",\n      \"key_metrics\": { \"security_grade\": \"B+\", \"threat_level\": \"LOW\" }\n    },\n    \"what\": \"...\",\n    \"who\": \"...\",\n    \"how\": \"...\",\n    \"recommendations\": [\"...\", \"...\"]\n  },\n  \"meta\": {\n    \"analysis_type\": \"wallet_analysis\",\n    \"direct_tool_execution\": true\n  }\n}\n```\n\n### 9.1 Endpoint Lain\n\n#### a. /pre-transaction (POST)\nDigunakan sebelum mengeksekusi transaksi on-chain (screening preventif).\nRequest:\nRequest:\n```json\n{\n  \"data\": {\n    \"wallet_address\": \"BQjmJq8EVptiTn5XbWHDA6FyeXC6qkijAjN6UojED1Mf\",\n    \"chain\": \"solana\",\n    \"analysis_type\": \"pre_transaction\",\n    \"check_type\": \"destination_wallet\"\n  }\n}\n```\nQuery opsional: ?direct_tool_execution=false  \n\n#### b. /check-wallet (GET)\nAnalisa fokus wallet saja.\n```bash\ncurl \"http://localhost:8000/check-wallet?wallet_address=DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6zDvNrjggrE3wTBas\u0026chain=solana\u0026direct_tool_execution=true\"\n```\n\n#### c. /transactions (GET)\nHistori transaksi (raw) via Helius.\n```bash\ncurl \"http://localhost:8000/transactions?wallet_address=DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6zDvNrjggrE3wTBas\"\n```\n\n#### d. /transfers (GET)\nToken transfer (indikasi spam / airdrop berisiko).\n```bash\ncurl \"http://localhost:8000/transfers?wallet_address=DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6zDvNrjggrE3wTBas\"\n```\n\n#### e. /domains (GET)\nSNS / domain mapping.\n```bash\ncurl \"http://localhost:8000/domains?wallet_address=DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6zDvNrjggrE3wTBas\"\n```\n\n#### f. /labels (GET)\nLabel reputasi (scam / phishing / exchange).\n```bash\ncurl \"http://localhost:8000/labels?wallet_address=DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6zDvNrjggrE3wTBas\"\n```\n\n#### g. Ringkasan Cepat Perbedaan\n| Endpoint | Fokus | Output Inti |\n|----------|-------|-------------|\n| /analyze | Gabungan multi-aspek | Full security_scores + summaries |\n| /pre-transaction | Gate sebelum eksekusi | Tambahan pre_transaction_recommendations |\n| /check-wallet | Hanya wallet | wallet_analysis + wallet_summary |\n| /transactions | Raw histori | Array transaksi mentah |\n| /transfers | Token movement | Deteksi spam / pattern token |\n| /domains | Domain wallet | daftar domain SNS |\n| /labels | Label reputasi | Kategori / tag wallet |\n\n\u003e Catatan: Endpoint raw (transactions/transfers/domains/labels) tidak selalu memiliki field scoring; scoring penuh hanya pada /analyze \u0026 /pre-transaction (serta derivasi /check-wallet).\n\n## 10. Pre-Transaction Flow\n- Tambahan field pre_transaction_recommendations\n- Jika risk HIGH/CRITICAL → blokir / manual review\n- Jika LOW/VERY_LOW → APPROVED\n\n## 11. Konfigurasi \u0026 Variabel Lingkungan (Disarankan)\nGanti hard-coded API key di kode agar aman:\n```\nexport CHAINABUSE_API_KEY=...\nexport BLOCKSEC_API_KEY=...\nexport HELIUS_API_KEY=...\nexport MISTRAL_API_KEY=...\n```\nLalu modifikasi agents.py \u0026 supervisor.py untuk membaca via os.getenv.\n\n## 12. Instalasi\n```\npython -m venv .venv\nsource .venv/Scripts/activate (Windows: .venv\\Scripts\\activate)\npip install -r requirements.txt\n# atau (editable install)\npip install -e .\n```\n\n## 12.1 Environment Variables\nBuat file `.env` (lihat `.env.example`):\n```\nCP=cp .env.example .env  # Linux/Mac\n```\nIsi sesuai API keys Anda.\n\n## 12.2 Jalankan Aplikasi\n```\nuvicorn main:app --host 0.0.0.0 --port 8000\n```\n\n## 12.3 Docker\nBuild \u0026 run:\n```\ndocker build -t sentrysol .\ndocker run --env-file .env -p 8000:8000 sentrysol\n```\n\n## 12.4 Health Quick Test\n```\ncurl -X POST http://localhost:8000/analyze -H \"Content-Type: application/json\" -d '{\"data\":{\"wallet_address\":\"\u003cWALLET\u003e\",\"chain\":\"solana\"}}'\n```\n\n## 21. Deployment Notes\n- Semua kunci API sudah dipanggil lewat `os.getenv()`.\n- Jika MISTRAL_API_KEY tidak ada → inisialisasi LLM akan gagal dan sistem fallback mencatat log error.\n- Gunakan process manager (pm2 / systemd / ECS / K8s) untuk produksi.\n- Set `PYTHONUNBUFFERED=1` agar log realtime di container.\n\n## 13. Ekstensi / Kustomisasi\nTambahkan tool baru:\n1. Definisikan fungsi di agents.py\n2. Bungkus dengan Tool(name=..., func=..., description=...)\n3. Tambahkan ke list tools di supervisor.py\n4. Perbarui prompt template bila perlu\n\n## 14. Error Handling \u0026 Fallback\n- Agent-based gagal → create_fallback_analysis\n- LLM scoring gagal → fallback skor default (moderate risk neutral)\n- Dynamic summary gagal → fallback statis\n\n## 15. Logging\n- app.log (API level)\n- supervisor.log (pipeline \u0026 scoring)\n- agents.log (pemanggilan tool)\n\n## 16. Keamanan \u0026 Pertimbangan\n- Jangan commit API key.\n- Rate limit eksternal (Helius, Metasleuth, Chainabuse).\n- Sanitasi input (panjang address, format).\n- Tambah auth (API key header) sebelum produksi.\n- Tambahkan cache (misal Redis) untuk mengurangi panggilan identik.\n\n## 17. Roadmap (Saran)\n- Integrasi on-chain anomaly model khusus.\n- Penambahan reputasi kontrak \u0026 dex interaction heuristics.\n- Integrasi SIEM / webhook alert.\n- Batch large-scale risk scoring + streaming.\n- OpenMetrics exporter (Prometheus).\n\n## 18. FAQ Singkat\nQ: Kenapa skor bisa berbeda antara mode agent \u0026 direct?  \nA: Agent mode menambah reasoning chain, bisa memicu variasi ringkasan sehingga mempengaruhi interpretasi LLM scoring.\n\nQ: Bisa multi-chain?  \nA: Saat ini deteksi Ethereum (0x...) \u0026 Solana (Base58). Dapat diperluas.\n\nQ: Apakah hasil selalu deterministik?  \nA: Tidak, bagian summary \u0026 scoring berbasis LLM (stochastic).\n\n## 19. Struktur Folder (Ringkas)\n```\nSentrySol-Langchain/\n ├─ main.py               (FastAPI endpoints)\n ├─ agents.py             (Tool definitions)\n ├─ supervisor.py         (Pipeline \u0026 orchestration)\n ├─ README.md             (Dokumentasi)\n ├─ *.log                 (Log runtime)\n```\n\n## 20. Interpretasi Cepat Hasil\n- overall_security_score \u003c 60 → Perlu investigasi lanjut.\n- risk_level HIGH/CRITICAL → Stop otomatis (policy saran).\n- confidence_level \u003c 50 → Minta re-run / manual review.\n- Banyak threat_indicators → Flag incident.\n\n--- \nJika memerlukan versi English atau penambahan diagram sequence detail, dapat ditambahkan kemudian.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffikriaf%2Fsentrysol-langchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffikriaf%2Fsentrysol-langchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffikriaf%2Fsentrysol-langchain/lists"}