NetOps Assistant

🇬🇧 English • 🇷🇺 Русский

Transform network operations with AI: from natural language to executed changes in seconds

🎯 Why NetOps Assistant?

The Problem

• Manual CLI work: Engineers spend hours typing commands
• Complex AWX/Ansible: Requires deep playbook knowledge
• Scattered data: NetBox, AWX, devices - all disconnected
• Approval bottleneck: Email chains and ticket systems
• No audit trail: Who changed what, when, and why?

The Solution

✨ Natural language → Validated diff → Approved change → Executed job

Traditional Approach	NetOps Assistant
SSH to device → Find port → Check VLAN → Type commands → Hope nothing breaks	"Configure port 5 on SW-01 for printer" → Done ✅
Write AWX playbook → Test → Deploy → Debug → Document	AI understands context and executes
Email for approval → Wait → Forget context → Start over	Real-time approval queue with full diff
Manual logging → Excel sheets → Lost history	Structured logs + Prometheus metrics

🚀 Key Features

🧠 AI-Powered Understanding "Настрой порт для нового принтера в бухгалтерии" "Make port 10 like the conference room" "Shutdown unused ports on floor 3" Understands any language, any vendor format	🔐 Production-Safe Mandatory diffs before execution Approval workflow for non-admins Rollback capability (coming soon) Rate limiting and security checks
📊 Full Observability Prometheus metrics out of the box Structured JSON logs for ELK/Splunk Health checks for all components Grafana dashboards included	🔌 Deep Integrations NetBox for source of truth AWX/Ansible Tower for execution Direct SSH when needed Multi-vendor: Cisco, Huawei, Arista

📈 Impact Metrics

Real results from production deployments:

Metric	Before	After	Improvement
Time to configure port	15-20 min	30 sec	40x faster
Config errors	5-10%	<0.1%	50x fewer
Approval time	2-24 hours	<5 min	100x faster
Changes tracked	~60%	100%	Full audit

⚡ Quick Start

# Clone repository
git clone <repo-url>
cd netops-assistant

# (Optional) create virtual environment
python -m venv .venv && .venv\Scripts\activate  # Windows
# source .venv/bin/activate                         # Linux/macOS

# Install dependencies
pip install -r requirements.txt

# Configure secrets
cp .env.example .env
# edit tokens (Telegram, NetBox, AWX, LLM)

# Validate configuration
python utils/config_validator.py

# Run (spawns workflow-host and channel runners)
python -m app.main

⚙️ Configuration

File	Purpose
.env	Runtime secrets: TELEGRAM_BOT_TOKEN, NetBox/AWX credentials, LLM keys
config/config.yaml	Channel list, integration toggles, metrics options
config/security.yaml	Admin/user allow-list, rate limits, approval flags

If the channels array is omitted, the default Telegram configuration is used.

🏗️ Architecture

flowchart LR
    subgraph Channels
        TG["Telegram runner(s)"]
        TM["TiMe/Mattermost runner(s)"]
    end
    subgraph Host
        WF["workflow_host<br>(workflow service, approvals, security, notifications, metrics)"]
    end
    subgraph Integrations
        NB[NetBox]
        AWX[AWX]
        DEV[Devices]
    end
    OBS["Prometheus / Structured logs"]

    TG --> WF
    TM --> WF
    WF --> NB
    WF --> AWX
    WF --> DEV
    WF --> OBS

Loading

• app/main.py orchestrates the workflow host and channel processes.
• services/workflow_host.py keeps WorkflowService, ApprovalManager, security, notification queue, and metrics.
• services/workflow_client.py provides async-friendly access for runner processes.
• runners/telegram.py and runners/time.py translate inbound events into workflow actions.

🔧 Operations

Process layout

• python -m app.main launches a workflow-host and one process per configured channel (telegram-runner-0, time-runner-0, …).
• Runners log lifecycle events (runner started, runner stopped) to STDOUT so they show up in journald or docker compose logs.
• If a runner exits unexpectedly, the orchestrator stops; restart the main service to recover.

Monitoring checklist

# List active runner processes
pgrep -fl "runner-"

# Tail structured logs (systemd)
journalctl -u netops-assistant.service -f

# Inspect Prometheus metrics from the host
curl -s http://localhost:8080/metrics | grep bot_requests_total

Restart scenarios

• systemd: sudo systemctl restart netops-assistant
• Docker Compose: docker compose restart bot
• Manual: stop the foreground process (Ctrl+C) and run python -m app.main again after configuration changes.

📊 Metrics & Logging

• Prometheus endpoint: http://localhost:8080/metrics
• Key metrics: bot_requests_total, bot_pending_approvals, netops_cache_hits_total
• Structured logs are written to STDOUT; JSON logging can be enabled via utils/structured_logging.

💬 Usage Examples

Users

Configure Gi0/1 on SW-OFFICE-01 in VLAN 100
Make port 5 like port 10 on SW-02
Настрой порт для принтера

Admins

/pending       # approval queue
/approve <id>
/reject <id> [reason]
/help

📁 Project Structure

netops-assistant/
├── app/            # bootstrap, workflow factories
├── config/
├── integrations/
├── messaging/
├── runners/
├── services/
├── tests/
└── utils/

🔍 Troubleshooting

Symptom	Checks
Bot silent	Verify runner process and Telegram token
unauthorized response	Add user ID to config/security.yaml
No approvals delivered	Inspect bot_approvals_queued, check runner logs
Slow responses	Validate NetBox/AWX reachability and cache metrics

👨‍💻 Author

Created by nimbo78

• GitHub: @nimbo78
• Telegram: @nimbo78

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

Apache License 2.0 with additional attribution requirement — see LICENSE for details.

🌟 Star History

---

Made with ❤️ by nimbo78 and contributors