devopsiq 0.1.0__py3-none-any.whl

tools/newrelic.py

@@ -0,0 +1,167 @@
+"""Read-only New Relic tools (Phase 9).
+
+Query New Relic's NerdGraph GraphQL API over curl: NRQL queries
+(newrelic_nrql) and the account's open alert incidents (newrelic_alerts).
+This extends the tools/monitoring.py pattern from GET to POST — the argv is
+still fixed, but here curl carries a `-d` payload built by json.dumps, so
+quoting is safe and the NRQL text can never break out of its JSON string.
+
+Credentials come from ENVIRONMENT CONFIGURATION only, never the model:
+- NEW_RELIC_API_KEY   — a NerdGraph (user) API key; unset → honest ToolError
+  naming the variable. It is passed to curl as a header value only.
+- NEW_RELIC_ACCOUNT_ID — the numeric account id; must be digits (it is
+  interpolated into the GraphQL variables as an integer, so a non-digit
+  value is refused rather than smuggled in).
+
+The model supplies ONLY the NRQL text (bounded length). newrelic_alerts
+takes no model input at all — its payload is byte-identical every call.
+Nothing here can create, acknowledge or close an incident; NerdGraph
+mutations are never sent (the GraphQL documents below are queries only).
+"""
+
+import json
+import os
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+_TIMEOUT_S = 20
+_MAX_QUERY_CHARS = 500
+_NERDGRAPH_URL = "https://api.newrelic.com/graphql"
+
+# Queries use GraphQL variables ($account, $nrql) — the payload is built by
+# json.dumps, so no NRQL text can escape its string slot.
+_NRQL_QUERY = (
+    "query ($accountId: Int!, $nrql: Nrql!) {"
+    "  actor {"
+    "    account(id: $accountId) {"
+    "      nrql(query: $nrql) {"
+    "        results"
+    "        metadata { facets queries}"
+    "      }"
+    "    }"
+    "  }"
+    "}"
+)
+
+_ALERTS_QUERY = (
+    "query ($accountId: Int!) {"
+    "  actor {"
+    "    account(id: $accountId) {"
+    "      alerts {"
+    "        incidents(filter: {states: [ACTIVE, ACKNOWLEDGED]}) {"
+    "          incidentId title priority state startedAt"
+    "          labels { key value }"
+    "        }"
+    "      }"
+    "    }"
+    "  }"
+    "}"
+)
+
+
+def _checked_query(args: dict, label: str) -> str:
+    query = args.get(label)
+    if not isinstance(query, str) or not query.strip():
+        raise ToolError(f"{label} must be a non-empty NRQL query string")
+    if len(query) > _MAX_QUERY_CHARS:
+        raise ToolError(f"{label} must be at most {_MAX_QUERY_CHARS} characters")
+    return query
+
+
+def _credentials() -> tuple[str, int]:
+    api_key = os.environ.get("NEW_RELIC_API_KEY", "").strip()
+    if not api_key:
+        raise ToolError(
+            "no New Relic credentials configured: set the NEW_RELIC_API_KEY "
+            "environment variable (a NerdGraph user key) and retry"
+        )
+    account_id = os.environ.get("NEW_RELIC_ACCOUNT_ID", "").strip()
+    if not account_id:
+        raise ToolError(
+            "no New Relic account configured: set the "
+            "NEW_RELIC_ACCOUNT_ID environment variable (digits only) and retry"
+        )
+    if not account_id.isdigit():
+        raise ToolError(
+            "NEW_RELIC_ACCOUNT_ID must be the numeric account id "
+            f"(got {account_id!r})"
+        )
+    return api_key, int(account_id)
+
+
+def _nerdgraph(api_key: str, payload: str) -> str:
+    return read_command_output(
+        (
+            "curl", "-sS", "--max-time", "15",
+            "-H", f"API-Key: {api_key}",
+            "-H", "content-type: application/json",
+            "-d", payload,
+            _NERDGRAPH_URL,
+        ),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _newrelic_nrql(args: dict) -> str:
+    nrql = _checked_query(args, "query")
+    api_key, account_id = _credentials()
+    payload = json.dumps({
+        "query": _NRQL_QUERY,
+        "variables": {"accountId": account_id, "nrql": nrql},
+    })
+    return _nerdgraph(api_key, payload)
+
+
+def _newrelic_alerts(args: dict) -> str:
+    # No model input reaches the payload — args are accepted and ignored.
+    api_key, account_id = _credentials()
+    payload = json.dumps({
+        "query": _ALERTS_QUERY,
+        "variables": {"accountId": account_id},
+    })
+    return _nerdgraph(api_key, payload)
+
+
+NEWRELIC_NRQL = Tool(
+    name="newrelic_nrql",
+    description=(
+        "Run one NRQL query against the configured New Relic account "
+        "(NEW_RELIC_API_KEY + NEW_RELIC_ACCOUNT_ID env) via the NerdGraph "
+        "API and return the JSON results. Use for APM/infra evidence: "
+        "error rates, response times, throughput, host resource metrics, "
+        "e.g. 'SELECT average(duration) FROM Transaction WHERE "
+        "appName = 'api' TIMESERIES SINCE 30 minutes ago'. Query text "
+        "only; credentials and account are fixed by the operator's "
+        "environment. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "NRQL query text, e.g. 'SELECT count(*) "
+                "FROM Transaction SINCE 1 hour ago'.",
+            }
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+    executor=_newrelic_nrql,
+)
+
+NEWRELIC_ALERTS = Tool(
+    name="newrelic_alerts",
+    description=(
+        "List the New Relic account's OPEN alert incidents (ACTIVE or "
+        "ACKNOWLEDGED) as JSON via NerdGraph: incident id, title, priority, "
+        "state, start time, entity labels. Use as the first step when an "
+        "alert fires — 'what is alerting right now'. No parameters; "
+        "credentials come from the environment. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_newrelic_alerts,
+)
+
+register(NEWRELIC_NRQL)
+register(NEWRELIC_ALERTS)

tools/preflight.py

@@ -0,0 +1,59 @@
+"""Read-only host inspection tool — the first *real* tool.
+
+This proves the whole tool loop (model requests a tool -> local executor
+runs a real command -> real output is fed back as evidence) while staying
+strictly read-only.
+
+Safety model (defense in depth):
+- The model may only choose among the static commands below; its parameters
+  select an allowlisted command and can never carry arbitrary command text.
+- The executor re-validates every argument against the allowlist before
+  running anything. Never trust the model's arguments.
+- All commands are read-only and harmless: date, uname, uptime, df, free.
+  Mutating verbs cannot appear here by construction.
+"""
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+# Static, allowlisted invocations. NEVER interpolate model-provided text here.
+_COMMANDS: dict[str, tuple[str, ...]] = {
+    "date_utc": ("date", "-u", "+%Y-%m-%dT%H:%M:%SZ"),
+    "uname": ("uname", "-a"),
+    "uptime": ("uptime",),
+    "disk_usage": ("df", "-h", "-T"),
+    "memory": ("free", "-h"),
+}
+
+
+def _run_allowlisted(args: dict) -> str:
+    command_key = args.get("command")
+    if not isinstance(command_key, str) or command_key not in _COMMANDS:
+        allowed = ", ".join(sorted(_COMMANDS))
+        raise ToolError(f"unknown command {command_key!r}; allowed commands: {allowed}")
+    return read_command_output(_COMMANDS[command_key])
+
+
+SYSTEM_INFO = Tool(
+    name="system_info",
+    description=(
+        "Inspect the host machine the agent runs on. Returns one read-only "
+        "fact: current UTC timestamp, OS/kernel info, uptime, disk usage, or "
+        "memory usage."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "enum": sorted(_COMMANDS),
+                "description": "Which read-only fact to collect from the host.",
+            }
+        },
+        "required": ["command"],
+        "additionalProperties": False,
+    },
+    executor=_run_allowlisted,
+)
+
+register(SYSTEM_INFO)

tools/registry.py

@@ -0,0 +1,49 @@
+"""Tool registry: the single place tools are declared and executed.
+
+Tools self-register by calling `register(tool)` at import time (see
+tools/preflight.py). The agent pulls the full list with `get_tools()` and
+executes model-requested calls through `execute_tool()`, which never raises:
+every failure is converted into an error string the model can read and adapt
+to, keeping the conversation loop alive.
+"""
+
+import json
+
+from tools.base import Tool, ToolError
+
+_TOOLS: dict[str, Tool] = {}
+
+
+def register(tool: Tool) -> None:
+    if tool.name in _TOOLS:
+        raise ValueError(f"a tool named {tool.name!r} is already registered")
+    _TOOLS[tool.name] = tool
+
+
+def get_tools() -> list[Tool]:
+    return list(_TOOLS.values())
+
+
+def execute_tool(name: str, arguments: str) -> str:
+    """Execute one tool call and return the text to feed back to the model.
+
+    Never raises. Failures (unknown tool, unparseable arguments, executor
+    errors) are returned as "Tool error: ..." strings so the model can read
+    them, apologize, or re-request with valid arguments.
+    """
+    tool = _TOOLS.get(name)
+    if tool is None:
+        known = ", ".join(sorted(_TOOLS)) or "none"
+        return f"Tool error: unknown tool {name!r}. Available tools: {known}."
+
+    try:
+        args = json.loads(arguments) if arguments and arguments.strip() else {}
+        if not isinstance(args, dict):
+            raise TypeError("tool arguments must be a JSON object")
+        return tool.executor(args)
+    except json.JSONDecodeError as exc:
+        return f"Tool error: could not parse arguments JSON: {exc}"
+    except ToolError as exc:
+        return f"Tool error: {exc}"
+    except Exception as exc:  # noqa: BLE001 - last resort; keep the loop alive
+        return f"Tool error: {type(exc).__name__}: {exc}"

tools/system.py

@@ -0,0 +1,162 @@
+"""Read-only Linux system tools (Phase 5).
+
+Four tools for on-host operational problems: service status (systemctl),
+service journal logs (journalctl), open TCP ports (ss), and the top CPU
+consumers (ps). Same contract and safety model as the other modules.
+
+Safety model:
+- Only fixed argv templates are ever built: `systemctl status <unit>
+  --no-pager`, `journalctl -u <unit> --no-pager -n <lines>`, `ss -tlnp`,
+  `ps aux --sort=-%cpu --no-headers`. No free-form command text, no shell.
+- The unit name is validated against systemd's allowed character set
+  (letters, digits, '.', '-', '_', '@', ':') with no leading dash — this
+  blocks path separators ('/'), flag injection ("-l"), and garbage.
+- Every command is read-only: status/log inspection and listing, nothing
+  that starts, stops, edits, or reloads a unit.
+- systemctl/journalctl/ss/ps must be installed on the host; if missing the
+  exact error is returned — nothing is invented.
+"""
+
+import re
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+# systemd unit names: letters, digits, and '.', '-', '_', '@', ':' — no '/',
+# no leading dash, max 255 chars.
+_UNIT_RE = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._@:\-]{0,253})?")
+_UNIT_LIMIT = 255
+
+# journalctl can sit waiting on a busy journal; bound every call.
+_TIMEOUT_S = 10
+
+
+def _check_unit(value, kind: str) -> str:
+    if (
+        not isinstance(value, str)
+        or len(value) > _UNIT_LIMIT
+        or not _UNIT_RE.fullmatch(value)
+    ):
+        raise ToolError(
+            f"invalid systemd unit name {value!r}: expected letters, digits, "
+            "'.', '-', '_', '@' or ':', max 255 chars (e.g. 'sshd', "
+            "'docker.service', 'ssh@0.0.0.0:22')"
+        )
+    return value
+
+
+def _sys_service_status(args: dict) -> str:
+    unit = _check_unit(args.get("unit"), "unit")
+    return read_command_output(
+        ("systemctl", "status", unit, "--no-pager"), timeout=_TIMEOUT_S
+    )
+
+
+def _sys_service_logs(args: dict) -> str:
+    unit = _check_unit(args.get("unit"), "unit")
+    try:
+        lines = int(args.get("lines", 100))
+    except (TypeError, ValueError):
+        raise ToolError("lines must be an integer between 1 and 500")
+    if not 1 <= lines <= 500:
+        raise ToolError("lines must be between 1 and 500")
+    return read_command_output(
+        ("journalctl", "-u", unit, "--no-pager", "-n", str(lines)),
+        timeout=_TIMEOUT_S,
+    )
+
+
+def _sys_open_ports(args: dict) -> str:
+    return read_command_output(("ss", "-tlnp"), timeout=_TIMEOUT_S)
+
+
+def _sys_top_processes(args: dict) -> str:
+    return read_command_output(
+        ("ps", "aux", "--sort=-%cpu", "--no-headers"), timeout=_TIMEOUT_S
+    )
+
+
+SYS_SERVICE_STATUS = Tool(
+    name="sys_service_status",
+    description=(
+        "Fetch the status of one systemd unit (service, socket, target, ...): "
+        "loaded/active state, Main PID, and the most recent journal lines. The "
+        "primary tool for 'why is this service down / restarting'. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "unit": {
+                "type": "string",
+                "description": "Unit name, e.g. 'sshd', 'docker.service', "
+                "'multi-user.target', 'ssh@0.0.0.0:22'.",
+            }
+        },
+        "required": ["unit"],
+        "additionalProperties": False,
+    },
+    executor=_sys_service_status,
+)
+
+SYS_SERVICE_LOGS = Tool(
+    name="sys_service_logs",
+    description=(
+        "Fetch the tail of a systemd unit's journal logs via journalctl. Use "
+        "with sys_service_status to see the actual error lines a service wrote "
+        "before failing/restarting. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "unit": {
+                "type": "string",
+                "description": "Unit name, e.g. 'sshd', 'docker.service'.",
+            },
+            "lines": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 500,
+                "default": 100,
+                "description": "How many lines to tail (1–500).",
+            },
+        },
+        "required": ["unit"],
+        "additionalProperties": False,
+    },
+    executor=_sys_service_logs,
+)
+
+SYS_OPEN_PORTS = Tool(
+    name="sys_open_ports",
+    description=(
+        "List TCP ports currently listening on the host (ss -tlnp), with the "
+        "process that owns each socket. Use for 'is port X in use', 'what is "
+        "bound to this port', port conflicts. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {},
+        "additionalProperties": False,
+    },
+    executor=_sys_open_ports,
+)
+
+SYS_TOP_PROCESSES = Tool(
+    name="sys_top_processes",
+    description=(
+        "List the processes consuming the most CPU on the host (ps aux sorted "
+        "by %cpu, no header). Use for 'what is eating CPU', runaway processes. "
+        "Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {},
+        "additionalProperties": False,
+    },
+    executor=_sys_top_processes,
+)
+
+register(SYS_SERVICE_STATUS)
+register(SYS_SERVICE_LOGS)
+register(SYS_OPEN_PORTS)
+register(SYS_TOP_PROCESSES)

tools/terraform.py

@@ -0,0 +1,90 @@
+"""Read-only Terraform tools (Phase 5).
+
+Three tools for infrastructure-as-code problems: what the current state holds
+(terraform state list), what a plan would change (terraform plan), and a
+human-readable render of the state (terraform show). All operate on the
+current working directory the agent was launched from.
+
+Safety model:
+- Only `show`, `state list`, and `plan` exist. There is no apply, destroy,
+  import, force-unlock, refresh (mutating), workspace delete, or taint.
+- `plan` is a dry run: it computes the diff but changes nothing. Pinned to
+  `-input=false` so it can never sit waiting on a prompt, and `-no-color`
+  keeps output model-readable.
+- A generous timeout (60s for plan — providers may need to fetch schemas)
+  bounds slow modules.
+- terraform must be installed and the directory must be initialized
+  (`terraform init`). If not, the exact error is returned — nothing is
+  invented. On a fresh directory the model sees terraform's own
+  "Please run 'terraform init'" and must report it, not fabricate state.
+"""
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+# Plan can take much longer than the default 10s on a real module (provider
+# schema downloads); everything else stays snappy.
+_PLAN_TIMEOUT_S = 60
+_OTHER_TIMEOUT_S = 15
+
+
+def _tf_show(args: dict) -> str:
+    return read_command_output(
+        ("terraform", "show", "-no-color"), timeout=_OTHER_TIMEOUT_S
+    )
+
+
+def _tf_state_list(args: dict) -> str:
+    return read_command_output(
+        ("terraform", "state", "list"), timeout=_OTHER_TIMEOUT_S
+    )
+
+
+def _tf_plan(args: dict) -> str:
+    return read_command_output(
+        ("terraform", "plan", "-no-color", "-input=false"),
+        timeout=_PLAN_TIMEOUT_S,
+    )
+
+
+TF_SHOW = Tool(
+    name="tf_show",
+    description=(
+        "Render the current Terraform state of the working directory "
+        "(terraform show): resources with their attribute values as stored. "
+        "Use to see what IaC currently believes exists. Requires an "
+        "initialized directory. Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_tf_show,
+)
+
+TF_STATE_LIST = Tool(
+    name="tf_state_list",
+    description=(
+        "List every resource address in the Terraform state of the working "
+        "directory (terraform state list), e.g. aws_instance.web. Use to see "
+        "what infrastructure is tracked and spot drift from config. "
+        "Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_tf_state_list,
+)
+
+TF_PLAN = Tool(
+    name="tf_plan",
+    description=(
+        "Dry-run Terraform plan for the working directory "
+        "(terraform plan -no-color -input=false): prints what would be "
+        "added/changed/destroyed — WITHOUT changing anything. Use to assess "
+        "the impact of local config changes or detect drift. Requires an "
+        "initialized directory. Read-only; may take up to 60s on large "
+        "modules."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_tf_plan,
+)
+
+register(TF_SHOW)
+register(TF_STATE_LIST)
+register(TF_PLAN)

tools/trivy.py

@@ -0,0 +1,83 @@
+"""Read-only security-scanning tools (Phase 9).
+
+One tool: trivy image scan — a vulnerability report for a container image
+(`trivy image --scanners vuln --format table <image>`). Trivy scans are
+read-only: they pull the image and the vulnerability database and print a
+report; nothing on this host or the registry is modified.
+
+Safety model:
+- Fixed argv template — the model may only choose the image reference.
+- Image references are validated: letters, digits, '.', '-', '_', '/', ':',
+  '@' only; must start (and end) alphanumeric, no leading '-', max 200
+  characters. This blocks flag injection (refs starting with '-') and
+  anything shell-ish — and there is no shell anyway (argv only).
+- The subprocess timeout is long (180s) because a cold trivy download of
+  the vulnerability database can take a while; the tool says so in its
+  description so the model can warn the user.
+- trivy must be installed; if missing, the exact error is returned.
+"""
+
+import re
+
+from tools.base import Tool, ToolError, read_command_output
+from tools.registry import register
+
+# Container image reference: registry/repo:tag@digest shape, alnum at the
+# ends, no leading '-' (no flag injection), no spaces.
+_IMAGE_RE = re.compile(
+    r"[a-zA-Z0-9][a-zA-Z0-9._@/\-]*(?::[a-zA-Z0-9._\-]+)?"
+)
+
+_TIMEOUT_S = 180
+
+
+def _check_image(value, kind: str = "image reference") -> str:
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= 200
+        or not _IMAGE_RE.fullmatch(value)
+        or not value[-1].isalnum()
+        or " " in value
+    ):
+        raise ToolError(
+            f"invalid {kind} {value!r}: expected a container image reference "
+            "like 'nginx:1.27' or 'registry.example.com/team/api:v2' "
+            "(letters, digits, '.', '-', '_', '/', ':', '@'; no leading '-')"
+        )
+    return value
+
+
+def _trivy_image_scan(args: dict) -> str:
+    image = _check_image(args.get("image"))
+    return read_command_output(
+        ("trivy", "image", "--scanners", "vuln", "--format", "table", image),
+        timeout=_TIMEOUT_S,
+    )
+
+
+TRIVY_IMAGE_SCAN = Tool(
+    name="trivy_image_scan",
+    description=(
+        "Scan a container image for vulnerabilities with Trivy and return "
+        "the report table: CVE id, severity, package, fixed version. Use "
+        "when a pod/container incident smells like a CVE, when triaging "
+        "'is this image safe to keep', or before recommending an image "
+        "bump. NOTE: the first run downloads the vulnerability database "
+        "and can take a couple of minutes. Read-only."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "image": {
+                "type": "string",
+                "description": "Image reference to scan, e.g. 'nginx:1.27' "
+                "or 'registry.example.com/team/api:v2'.",
+            }
+        },
+        "required": ["image"],
+        "additionalProperties": False,
+    },
+    executor=_trivy_image_scan,
+)
+
+register(TRIVY_IMAGE_SCAN)