-
Notifications
You must be signed in to change notification settings - Fork 2
getting started troubleshooting
Things don't always go according to plan, and that is okay! If you are running into issues with Siyarix, you have come to the right place.
Below are the most common issues users face and the exact steps to fix them.
Siyarix requires some modern Python features. Ensure you are running the correct version:
# 1. Verify you are running Python 3.11 or newer
python --version
# 2. Upgrade your pip (outdated pip is the #1 cause of install failures)
pip install --upgrade pip
# 3. Try installing again with verbose output to see exactly where it fails
pip install siyarix -v Sometimes, Python misses a dependency during a basic install. You can force it to pull down absolutely everything Siyarix needs by installing the [all] extra:
pip install "siyarix[all]"Your operating system might not have Python's scripts folder added to your system PATH.
# Workaround: You can always run Siyarix directly as a Python module!
python -m siyarix --version The Cause: Siyarix woke up, but it doesn't have a brain connected! You haven't provided any API keys, and there are no local AI engines running. The Fix:
# Option A: Give it a cloud key
export OPENAI_API_KEY="sk-..."
# Option B: Spin up a local, free AI engine
ollama pull llama3.1 && ollama serve
# Option C: Run in Offline mode (no AI needed!)
siyarix --mode offline run "scan example.com"The Cause: Siyarix cannot reach the AI provider's API endpoint. The Fix:
# 1. Let Siyarix diagnose the connection for you
siyarix health
# 2. Are you stuck behind a corporate proxy? Check your proxy settings
siyarix config get proxy
# 3. If a proxy is misconfigured, clear it out
siyarix config set proxy ""The Cause: Security tools often need to craft raw network packets (like nmap doing OS fingerprinting). Standard users don't have the OS permissions to do this.
The Fix: Run Siyarix with elevated privileges! Use sudo on Linux/macOS, or open your terminal as an Administrator on Windows.
The Cause: Siyarix is trying to use a security tool (like nmap), but it isn't installed on your actual computer. Siyarix orchestrates tools; it doesn't bundle them all.
The Fix:
# Debian/Ubuntu Linux
sudo apt install nmap
# macOS
brew install nmap
# Windows
winget install nmap
# Verify what Siyarix can see:
siyarix scan --list-tools If you run siyarix health and see red text, don't panic! The Health Checker breaks down exactly what is wrong. Look specifically at the components marked DEGRADED or UNHEALTHY—it will tell you if you are out of RAM, missing a tool, or failing to reach an API.
The Cause: Siyarix's encrypted vault might be corrupted, or your OS is missing the cryptography libraries needed to decrypt it. The Fix:
# 1. Ensure the encryption dependency is fully installed
pip install cryptography
# 2. Force Siyarix to re-initialize a fresh, healthy vault
siyarix init --force If the error messages aren't giving you enough context, you can turn on Debug Mode to see exactly what Siyarix is thinking under the hood.
# Enable it temporarily for a single session:
export SIYARIX_DEBUG=1
siyarix run "scan example.com"
# Or enable it permanently:
siyarix config set log_level debugIf your configuration is completely tangled and you just want to start fresh:
# Option A: Just reset your settings back to factory defaults
siyarix config reset
# Option B: The Nuclear Option (Deletes history, credentials, cache, and settings)
rm -rf ~/.siyarix Before pulling your hair out, ensure you aren't running into one of our known platform limitations:
- Python 3.10 and older are NOT supported. You must be on 3.11+.
- Windows raw sockets absolutely require Administrator privileges.
- Docker containers often lack native networking tools; you may need to install them inside the container.
- WSL2 (Windows Subsystem for Linux) network performance and bridging behaves differently than native Linux, which can affect scan accuracy.
We are here to help! If you have found a bug, please let us know:
- Enable debug logging:
export SIYARIX_DEBUG=1 - Run the diagnostic tool:
siyarix health - Copy the output and open an issue on our GitHub Repository.
Please be sure to include your OS, your Python version, and the full text of the error!
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!