Skip to content

getting started first run

Jump to bottom
MD MUFTHAKHERUL ISLAM MIRAZ edited this page Jun 24, 2026 · 2 revisions

🏃‍♂️ Your First Run

You have installed Siyarix, and you are ready to take it for a spin. Awesome!

This guide will walk you through your very first session, from verifying the system health to executing a live command.

1️⃣ Launch and Onboard

To get started, simply type the following into your terminal:

siyarix

If this is your very first time running the program, the Onboarding Wizard will automatically launch. It will warmly guide you through setting up your AI provider and configuring your initial preferences.

(If you want to read more about what happens during this step, check out our Onboarding Wizard guide.)

2️⃣ Verify System Health

Before we start scanning networks, let's make sure everything is plugged in correctly. Siyarix has a built-in health checker that acts like a pre-flight checklist.

siyarix health

This command runs a comprehensive diagnostic sweep, checking:

  • System Requirements: Ensuring your Python version and OS are compatible.
  • Installed Tools: Scanning your PATH to make sure you have the necessary security binaries installed.
  • Credential Store: Verifying that your encrypted vault is unlocked and ready.
  • Provider Connectivity: Reaching out to your configured AI providers (like OpenAI or Ollama) to ensure their APIs are responding.
  • System Resources: Checking your memory and CPU to warn you if you might run out of RAM during heavy autonomous operations.

If it says you are healthy, you are cleared for takeoff! 🛫

3️⃣ Run a Pre-Configured Scan

Let's start with something simple. Siyarix comes with a few pre-configured workflows. Let's run a quick port scan against a domain.

siyarix scan quick example.com

What happens behind the scenes?

  1. Siyarix plans the operation.
  2. It routes the plan through the Permission Gate (so you can see exactly what it is about to do).
  3. It executes the tools in the background.
  4. It parses the messy terminal output into a clean, structured table.

Want to dig deeper?

If you want comprehensive reconnaissance (OS fingerprinting, vulnerability detection, etc.), try the deep scan:

siyarix scan deep example.com

4️⃣ Command with Natural Language

This is where the magic happens. Instead of typing out complex nmap flags, you can just tell Siyarix what you want to achieve in plain English.

siyarix run "enumerate services on 10.0.0.1 and find vulnerable versions"

The AI engine will interpret your request, select the best tools for the job, build an execution plan, and present you with the results.

🚫 Running Offline?

If you are in an air-gapped environment or don't want to use an AI provider, Siyarix has you covered. Just add the --mode offline flag:

siyarix --mode offline run "scan example.com"

In offline mode, Siyarix relies on a hardcoded heuristics registry to plan tasks—no AI dependency, and no API keys required!

5️⃣ Enter the Interactive REPL

Running single commands from the terminal is great, but Siyarix truly shines when you enter its interactive chat mode (the REPL).

siyarix

Once inside, you are in a multi-turn conversation with your AI security co-pilot. You can:

  • Type /run [prompt] to execute commands.
  • Type /persona to change the AI's mindset on the fly.
  • Enjoy context-aware tab completion for file paths, tools, and models!

🙋 Getting Help

If you ever get stuck, help is just a command away:

siyarix --help              # Top-level help menu
siyarix scan --help         # Help for a specific command

If you are inside the REPL, simply type /help to see a list of all available slash commands.

⏭️ What's Next?

You have successfully run your first scan! Here is where you can go from here:

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! ❤️

🗺️ Siyarix Documentation Map

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.

🧭 Quick Navigation

Not sure where to start? Pick the path that best describes you:

🌱 For New Users

Just getting started? We highly recommend following these guides in order:

  1. Installation Guide — Get Siyarix running on your machine.
  2. Onboarding Wizard — Let our interactive wizard help you set up your API keys and environment.
  3. Setup & Configuration — A deeper dive into customizing your setup.
  4. Your First Run — A gentle walkthrough of your very first Siyarix command.

🛡️ For Security Operators

Ready to put Siyarix to work? Dive into our operational guides:

💻 For Developers & Contributors

Looking under the hood or wanting to write some code? Start here:

📂 The Complete Documentation Tree

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

📖 Key Terminology

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!

Clone this wiki locally