{"id":50686495,"url":"https://github.com/saramazal/ghostshell","last_synced_at":"2026-06-08T23:30:29.271Z","repository":{"id":352261932,"uuid":"1213491836","full_name":"saramazal/ghostshell","owner":"saramazal","description":"🐉 GhostShell — AI Pentesting Assistant  GhostShell is a local AI-powered penetration testing assistant built with Node.js and Ollama.  It analyzes scan results, suggests attack paths, and outputs real commands to accelerate your penetration testing workflow.","archived":false,"fork":false,"pushed_at":"2026-04-18T16:56:37.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T18:38:35.820Z","etag":null,"topics":["ai-assistant","ai-tools","axios","curl","dig","ethical-hacking","ethical-hacking-tools","ffuf","javascript","llama3","login","mistral","nmap","nodejs","ollama","penetration-testing","penetration-testing-framework","penetration-testing-tools","scanner","whois"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/saramazal.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T12:45:12.000Z","updated_at":"2026-04-18T16:56:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/saramazal/ghostshell","commit_stats":null,"previous_names":["saramazal/ghostshell"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/saramazal/ghostshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saramazal%2Fghostshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saramazal%2Fghostshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saramazal%2Fghostshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saramazal%2Fghostshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saramazal","download_url":"https://codeload.github.com/saramazal/ghostshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saramazal%2Fghostshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34085321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"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-assistant","ai-tools","axios","curl","dig","ethical-hacking","ethical-hacking-tools","ffuf","javascript","llama3","login","mistral","nmap","nodejs","ollama","penetration-testing","penetration-testing-framework","penetration-testing-tools","scanner","whois"],"created_at":"2026-06-08T23:30:26.346Z","updated_at":"2026-06-08T23:30:29.264Z","avatar_url":"https://github.com/saramazal.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"* _project_in_progress_\n# 🐉 GhostShell — AI Pentesting Assistant\n\nGhostShell is a local AI-powered penetration testing assistant built with Node.js and Ollama.\n\nIt analyzes scan results, suggests attack paths, and outputs real commands to accelerate your penetration testing workflow.\n\n---\n\n## ⚙️ Features\n\n* 🧠 **AI-powered scan analysis** — Uses Llama3 for deep analysis\n* ⚔️ **Attack path suggestions** — Auto-detects exploit chains\n* 🔄 **Multi-model routing** — Smart model selection (llama3 + mistral)\n* 🧾 **Persistent memory** — RAG-based knowledge storage\n* 🔓 **Login detection** — Identifies authentication endpoints\n* 💻 **Command generation** — Outputs actionable exploitation commands\n* 🔧 **Tool integration** — nmap, ffuf, whois, dig, whatweb, curl\n\n---\n\n## 🧱 Tech Stack\n\n* **Node.js** — Runtime\n* **Ollama** — Local LLM inference engine\n* **Llama3** — Deep analysis model\n* **Mistral** — Fast task execution model\n* **Axios** — HTTP client for Ollama API\n* **fs-extra** — File utilities\n\n---\n\n## 🚀 Quick Start\n\n### 1. Install Ollama\n\nDownload from [ollama.ai](https://ollama.ai)\n\n### 2. Pull models\n\n```bash\nollama pull llama3\nollama pull mistral\n```\n\n### 3. Clone \u0026 setup\n\n```bash\ngit clone https://github.com/saramazal/ghostshell\ncd ghostshell\nnpm install\n```\n\n### 4. Start Ollama (in separate terminal)\n\n```bash\nollama serve\n```\n\n### 5. Run GhostShell\n\n```bash\nnode index.js 10.10.10.10 analysis\n```\n\n---\n\n## 📖 Usage\n\n### Option 1: Direct Node.js\n\n**Analyze target directly:**\n```bash\nnode index.js 10.10.10.10 analysis\n```\n\n**Analyze scan results file:**\n```bash\nnode index.js scan.txt analysis\n```\n\n### Option 2: CLI (Global Install)\n\n**Install as global command:**\n```bash\nnpm install -g .\n```\n\n**Use anywhere:**\n```bash\nghostshell scan 10.10.10.10\nghostshell recon 192.168.1.1\n```\n\n### Option 3: Direct Node CLI\n\n**Without global install:**\n```bash\nnode cli.js scan 10.10.10.10\nnode cli.js recon 192.168.1.1\n```\n\n---\n\n## 📁 Project Structure\n\n```\nghostshell/\n├── index.js              # Main entry point\n├── cli.js                # CLI interface (#!/usr/bin/env node)\n├── agent.js              # AI agent orchestration\n├── package.json          # Dependencies \u0026 bin config\n├── scan.txt              # Sample scan file\n├── memory/\n│   ├── history.json      # Execution history\n│   └── ragStore.js       # RAG memory persistence\n└── tools/\n    ├── runTool.js        # Tool executor\n    ├── analyzer.js       # Generic analyzer\n    ├── nmap.js           # Port scanning\n    ├── ffuf.js           # Web fuzzing\n    ├── whois.js          # Domain WHOIS lookup\n    ├── dig.js            # DNS queries\n    ├── whatweb.js        # Web fingerprinting\n    ├── curl_headers.js   # HTTP header analysis\n    ├── exploitPlanner.js # Exploit chain builder\n    └── parsers/\n        ├── ffufParser.js # Parse ffuf output\n        └── loginDetector.js # Detect login forms\n```\n\n---\n\n## 🎯 How It Works\n\n1. **Input** → Target IP or scan file\n2. **Recon Planning** → Mistral AI selects relevant tools\n3. **Tool Execution** → Runs whois, dig, nmap, ffuf, whatweb, etc.\n4. **Intel Gathering** → Detects logins, parses results\n5. **Analysis** → Llama3 deep analysis of findings\n6. **Exploitation** → Suggests attack chains and commands\n7. **Memory** → Saves results for future reference (RAG)\n\n---\n\n## ⚙️ Configuration\n\n### Choose LLM Models\n\nEdit `agent.js` `chooseModel()` function:\n\n```javascript\nfunction chooseModel(taskType, inputLength) {\n  if (taskType === \"analysis\") return \"llama3\";\n  return inputLength \u003e 1500 ? \"llama3\" : \"mistral\";\n}\n```\n\n### Ollama API Endpoint\n\nEdit `agent.js` `queryOllama()` function:\n\n```javascript\nasync function queryOllama(model, prompt) {\n  const res = await axios.post(\"http://localhost:11434/api/generate\", {\n    model,\n    prompt,\n    stream: false\n  });\n  return res.data.response;\n}\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### ❌ `Error: connect ECONNREFUSED localhost:11434`\n\n**Problem:** Ollama is not running\n\n**Solution:**\n```bash\nollama serve\n```\n\n### ❌ `Model not found: llama3`\n\n**Problem:** Model not downloaded\n\n**Solution:**\n```bash\nollama pull llama3\nollama pull mistral\n```\n\n### ❌ `JSON parse failed`\n\n**Problem:** Corrupted memory file\n\n**Solution:**\n```bash\nrm memory/rag.json\nrm memory/history.json\n```\n\n---\n\n## 📊 Memory System\n\nGhostShell learns from past scans using RAG (Retrieval Augmented Generation):\n\n- **rag.json** — Stores all discovered intelligence\n- **history.json** — Logs all executions with timestamps\n\nQuery past knowledge:\n```javascript\nconst { searchMemory } = require(\"./memory/ragStore\");\nconst past = searchMemory(\"10.10.10.10\");\n```\n\n---\n\n## 🛠️ Development\n\n### Run tests\n```bash\nnpm test\n```\n\n### Debug mode\n```bash\nDEBUG=* node index.js 10.10.10.10 analysis\n```\n\n### Check history\n```bash\ncat memory/history.json | jq .\n```\n\n---\n\n## ⚠️ Legal Notice\n\nGhostShell is for **authorized security testing only**. Unauthorized access to computer systems is illegal. Always obtain written permission before running penetration tests.\n\n---\n\n## 📝 License\n\nISC\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Feel free to:\n- Add new reconnaissance tools\n- Improve AI prompts\n- Enhance memory system\n- Fix bugs\n\nOpen a PR! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaramazal%2Fghostshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaramazal%2Fghostshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaramazal%2Fghostshell/lists"}