Skip to content

README.md

Latest commit

 

History

History
255 lines (191 loc) · 7.36 KB

README.md

File metadata and controls

255 lines (191 loc) · 7.36 KB
Raw

NetOps Assistant

Python Code style: black License: Apache 2.0 Docker Telegram

🇬🇧 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

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

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

🌟 Star History

Star History Chart

Made with ❤️ by nimbo78 and contributors