-
Notifications
You must be signed in to change notification settings - Fork 2
getting started troubleshooting
MD MUFTHAKHERUL ISLAM MIRAZ edited this page Jun 17, 2026
·
2 revisions
python --version # Ensure Python 3.11+
pip install --upgrade pip
pip install siyarix -v # Verbose outputpip install "siyarix[all]" # Ensure all deps installedpython -m siyarix --version # Run via module
# which siyarix (Linux/macOS)
# where siyarix (Windows)Cause: No API keys set and no local provider running.
Fix:
export OPENAI_API_KEY="sk-..." # Set a cloud key
ollama pull llama3.1 && ollama serve # Or start a local providerCause: Provider endpoint unreachable.
Fix:
siyarix config get proxy
siyarix config set proxy ""Cause: Insufficient permissions for network interfaces or raw sockets.
Fix: Run with elevated privileges (sudo on Linux/macOS, Administrator on Windows).
Cause: Security tools not found on PATH.
Fix:
sudo apt install nmap # Debian/Ubuntu
brew install nmap # macOS
winget install nmap # Windows
siyarix scan --list-tools # Verify tool registryexport SIYARIX_DEBUG=1
siyarix ...Or set persistent log level:
siyarix config set log_level debugsiyarix config reset # Reset settings to defaults
rm -rf ~/.siyarix # Full reset (settings, history, cache)- Python 3.11+ required; older versions not supported
- Windows raw sockets require Administrator privileges
- Docker environments may lack certain native tools
- WSL2 network performance may differ from native Linux
- Enable debug logging:
export SIYARIX_DEBUG=1 - Collect diagnostics:
siyarix health - Open an issue at https://github.com/mufthakherul/siyarix/issues
Include Python version, OS, and full error output.
Note
👋 Welcome to Siyarix! This is a personal passion project built by a single developer. It's currently under active development and growing fast. Expect rough edges, but lots of love! ❤️
Welcome to the Siyarix Documentation Map! This page serves as your master compass for navigating the extensive documentation we have built for the platform.
Whether you are a brand new user, a seasoned security operator, or a developer looking to contribute to the core engine, you can find exactly what you need here.
Not sure where to start? Pick the path that best describes you:
Just getting started? We highly recommend following these guides in order:
- Installation Guide — Get Siyarix running on your machine.
- Onboarding Wizard — Let our interactive wizard help you set up your API keys and environment.
- Setup & Configuration — A deeper dive into customizing your setup.
- Your First Run — A gentle walkthrough of your very first Siyarix command.
Ready to put Siyarix to work? Dive into our operational guides:
- Interactive Chat (REPL) — Learn how to use the powerful interactive terminal.
- Security Workflows — Best practices for recon, vulnerability assessment, and incident response.
- Cloud & IaC Scanning — How to secure your cloud environments and infrastructure code.
- Compliance Frameworks — Map your scans to SOC 2, HIPAA, ISO 27001, and more.
Looking under the hood or wanting to write some code? Start here:
- Contribution Guide — Our workflow, standards, and how you can help!
- Codebase Overview — A comprehensive map of our 82+ source modules.
- Testing Standards — How we ensure reliability with pytest and CI/CD.
- Module Architecture — Component design and responsibilities.
If you prefer to browse the raw structure, here is a complete layout of the docs/ folder:
docs/
├── 🚀 getting-started/ # Installation, onboarding, and configuration
│ ├── installation.md # Multi-platform install (pip, brew, winget, docker)
│ ├── onboarding.md # The interactive 11-step setup wizard
│ ├── setup.md # Managing API keys, credentials, and settings
│ ├── first-run.md # A walkthrough of your first session
│ ├── configuration.md # A deep-dive into advanced settings
│ └── troubleshooting.md # Common issues and how to fix them instantly
│
├── 📖 user/ # Daily operations and workflows
│ ├── cli-commands.md # Reference for 50+ CLI commands across 12 groups
│ ├── interactive-chat.md # Mastering the AI REPL and 54+ slash commands
│ ├── security-workflows.md # Recon, vulnerability assessment, incident response
│ ├── cloud-scanning.md # Multi-cloud security scanning (under development)
│ ├── compliance.md # Framework mapping (SOC 2, NIST, GDPR, PCI-DSS)
│ ├── threat-intelligence.md# Integrations with OTX, NVD, and MITRE ATT&CK
│ ├── playbooks.md # Building automated YAML-based IR playbooks
│ ├── workflow-files.md # DAG workflow reference (programmatic API)
│ ├── reporting.md # Multi-format report generation
│ ├── offline-registry.md # Running without AI (Offline/Registry execution mode)
│ └── ai-workflows.md # Advanced AI-driven autonomous operations
│
├── 💻 developer/ # Building, testing, and extending Siyarix
│ ├── codebase-overview.md # Full module structure mapping
│ ├── contribution-guide.md # How to submit PRs and our coding standards
│ ├── module-architecture.md# Component design and responsibilities
│ ├── testing.md # Writing tests (pytest), coverage, and CI/CD
│ └── building.md # Packaging, distribution, and Docker builds
│
├── 🏗️ architecture/ # System design and core internals
│ ├── overview.md # High-level data flow and layered orchestration
│ ├── ai-agent-pipeline.md # The AgentCore reasoning and execution pipeline
│ ├── provider-abstraction.md# How we unify 26 different AI providers
│ ├── execution-engine.md # Plan-based step orchestration
│ ├── memory-and-state.md # Knowledge graph, session persistence, and learning
│ ├── security-model.md # The Permission Gate, DLP, audit logging, and OPSEC
│ └── intent-routing.md # Semantic intent classification and routing
│
├── 🧠 ai/ # Deep dive into the AI provider & agent systems
│ ├── routing.md # Managing 26 providers, failovers, and circuit breakers
│ ├── persona-system.md # Overview of our 10 security personas
│ ├── agent-reasoning.md # The Observe-Reason-Act loop and tool call repair
│ ├── tool-execution.md # The tool registry, capability graph, and parsers
│ ├── ensemble.md # Parallel LLM voting strategies
│ ├── multi-wave.md # Iterative goal execution with context carry-over
│ ├── prompt-architecture.md# System prompt design and management
│ └── safety.md # Our rigorous 8-layer hallucination mitigation system
│
├── 🛡️ security/ # Safety, ethics, and threat models
│ ├── reporting.md # How to safely report vulnerabilities to us
│ ├── threat-model.md # System threat model and our mitigations
│ ├── operational-security.md# TOR routing, stealth modes, and OPSEC controls
│ ├── ethical-policy.md # Mandatory rules of engagement for all users
│ └── abuse-prevention.md # How we prevent misuse of the AI engine
│
└── ⚖️ legal/ # Licensing and governance
├── agpl-guide.md # A plain-English overview of the AGPL-3.0-or-later license
├── why-agpl.md # The philosophy behind our license choice
├── trademark-policy.md # Branding and trademark guidelines
├── responsible-ai.md # Our framework for ethical AI usage
├── disclaimer.md # Important legal disclaimers
└── plugin-exception.md # The license exception for building custom plugins
As you read through the documentation, you might encounter some specific terms. Here is a quick cheat sheet:
| Term | What It Means |
|---|---|
| Provider | The backend AI engine powering Siyarix (e.g., OpenAI, Anthropic, Ollama). |
| Tool | A traditional security executable installed on your system (e.g., nmap, nuclei). |
| Plan | A step-by-step sequence of tool commands intelligently generated by the AI. |
| Workflow | A hardcoded, predefined execution path (usually defined in YAML/JSON) that doesn't require AI generation. |
| Persona | A specialized behavioral profile given to the AI (e.g., instructing it to act specifically as a "Network Recon Specialist"). |
| Knowledge Graph | Siyarix's internal memory where it stores findings (like IP addresses, open ports) to contextually inform future steps. |
Need help finding something specific? Feel free to use the search bar at the top of the documentation site, or open a discussion on our GitHub!