https://github.com/aezizhu/g
Secure natural-language CLI for OpenWrt (LuCI UI, policy engine, Gemini/OpenAI/Anthropic).
https://github.com/aezizhu/g
anthropic automation cli devops embedded-linux fw4 gemini luci networking openai openwrt opkg policy-engine router security ubus uci
Last synced: about 1 month ago
JSON representation
Secure natural-language CLI for OpenWrt (LuCI UI, policy engine, Gemini/OpenAI/Anthropic).
- Host: GitHub
- URL: https://github.com/aezizhu/g
- Owner: aezizhu
- License: mit
- Created: 2025-08-29T06:42:43.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-08-29T08:24:26.000Z (about 1 month ago)
- Last Synced: 2025-08-29T12:20:10.301Z (about 1 month ago)
- Topics: anthropic, automation, cli, devops, embedded-linux, fw4, gemini, luci, networking, openai, openwrt, opkg, policy-engine, router, security, ubus, uci
- Language: Go
- Homepage: https://openwrt.org/
- Size: 26.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
g - Natural Language CLI for OpenWrt
====================================
Author: aezizhu
Overview
--------
g is a secure, extensible command-line utility that translates natural language requests into audited shell commands on headless Linux systems, with first-class support for OpenWrt. It combines deterministic planning, strict policy enforcement, and human-in-the-loop confirmations to make system administration safer and more intuitive.
Key Features
------------
- Natural-language to commands with structured plans
- Policy-based allow/deny validation and shell-free execution
- Dry-run, interactive approval, and full audit-friendly output
- OpenWrt focus: uci, ubus, fw4, opkg, diagnostics
- Provider-agnostic design, Gemini HTTP integration included
Quick Start
-----------
1. Build:
```bash
cd g
go build ./cmd/g
```
2. Configure API key using one of the following (precedence: env > UCI > file):
- Environment: `export GEMINI_API_KEY=...`
- OpenWrt UCI: `uci set g.@api[0]=api; uci set g.@api[0].key=...; uci commit g`
- JSON file: `/etc/g/config.json` or `$HOME/.config/g/config.json`
3. Run a dry-run request:
```bash
./g -dry-run "open port 22 on firewall for lan"
```
4. Approve and execute:
```bash
./g -dry-run=false -approve "restart wifi"
```
Safety Model
------------
- No shell expansion or pipelines; argv-only execution
- Policy engine with allowlist and denylist regexes
- Non-root by default; explicit elevation only when required
- Per-command timeouts and minimal environment
- Human confirmation unless `-approve` is set
Configuration
-------------
Config precedence is file < UCI < env. The config schema:
```json
{
"author": "aezizhu",
"api_key": "...",
"endpoint": "https://generativelanguage.googleapis.com/v1beta",
"model": "gemini-1.5-flash",
"dry_run": true,
"auto_approve": false,
"timeout_seconds": 30,
"max_commands": 10,
"allowlist": ["^uci(\\s|$)", "^ubus(\\s|$)"],
"denylist": ["^rm -rf /"],
"log_file": "/tmp/g.log"
}
```
CLI Flags
---------
- `-config`: path to JSON config file
- `-model`: model name (default: gemini-1.5-flash)
- `-dry-run`: only print plan (default: true)
- `-approve`: auto-approve plan
- `-timeout`: per-command timeout (default: 30s)
- `-max-commands`: max commands to run (default: 10)
- `-log-file`: execution log path (informational)
- `-version`: print version
Elevation
---------
- Some operations require root. If a plan marks a command with `needs_root: true`, the executor will prefix the argv with `elevate_command` when configured (e.g., `doas -n` or `sudo -n`).
- `-version`: print version
Development
-----------
- Go 1.21+
- Code layout:
```
cmd/g # CLI entrypoint
internal/config # config loader (env, UCI, file)
internal/llm # provider clients (Gemini)
internal/plan # planner schema and instructions
internal/policy # allow/deny validation
internal/executor # argv-only runner with timeouts
internal/ui # CLI I/O helpers
```
OpenWrt Notes
-------------
- Cross-compile with appropriate target (see `docs/OPENWRT.md`).
- UCI storage for API key is supported via `g.@api[0].key`.
- Ensure required tools exist in `PATH`: `uci`, `ubus`, `fw4`, `opkg`.
Security Considerations
-----------------------
- Keep allowlist narrowly scoped and review regularly.
- Avoid blanket `-approve` in unattended environments.
- Route logs to persistent storage if needed.
License
-------
SEO Topics and Keywords
-----------------------
- OpenWrt natural language CLI, router automation, LLM-assisted administration, firewall management, UCI automation, ubus integration, fw4 control, opkg package management, secure command execution, policy engine, dry-run approval workflow, headless Linux orchestration, embedded systems operations, network diagnostics automation, infrastructure as conversation.
About This Project
------------------
`g` aims to make router administration safer and faster by combining deterministic execution with human-readable intent. It focuses on OpenWrt first, with a provider-agnostic design and strong safety defaults.
MIT