Tools
Tfg Linux Diagnostics
By Restricted read-only Linux diagnostics plugin for OpenClaw (academic prototype).
Install
npm install -gREADME
# TFG Linux Diagnostics
Academic OpenClaw tool plugin for diagnosing a single Linux target through a
restricted SSH channel. It is intentionally a diagnosis-only prototype: it
does not remediate incidents or expose a shell to the model.
## Scope and security model
The model can only invoke linux_diagnostic. Its inputs select one of four fixed
read-only diagnostics: disk_usage, memory_status, package_status, and
service_status for nginx or tfg-broken.
The plugin validates these inputs with a closed schema, builds the SSH command
from fixed command templates, and invokes /usr/bin/ssh with execFile without a
shell. The operator configures the destination locally; the model cannot set
the SSH host, user, key path, command, service name, or script path.
The Debian side adds independent restrictions: a dedicated account, forced
command dispatcher, exact sudoers entries, and root-owned diagnostic scripts.
## Requirements
- Linux or WSL with OpenSSH client and Node.js compatible with the chosen
OpenClaw release.
- OpenClaw installed and available as openclaw.
- A dedicated Linux target for laboratory use.
- A dedicated SSH key and a verified host key in the operator's known_hosts
file.
The implementation was validated with OpenClaw 2026.7.1-2. Use this version
for reproducibility before evaluating a newer release.
Install that validated version and complete its local onboarding:
npm install -g openclaw@2026.7.1-2
openclaw onboard --install-daemon
## Build and validate
git clone <repository-url> tfg-linux-diagnostics
cd tfg-linux-diagnostics
npm ci
npm test
npm run plugin:build
npm run plugin:validate
npm run plugin:build compiles the TypeScript source and generates the manifest
from the built entry. Use npm run plugin:validate before loading it.
## Prepare the Linux target
Copy the four files in debian/ to /usr/local/sbin/tfg-diagnostics/, set their
owner to root:root and mode to 0755. Install the supplied
debian/ssh-diagnostic-dispatcher as a root-owned executable. Review
debian/diagnosticuser.sudoers, replace diagnosticuser with the dedicated
non-administrative account, validate it with visudo -cf, and install it under
/etc/sudoers.d/.
Configure that account's SSH public key with a forced command that invokes the
dispatcher. Do not reuse an administrator account and do not grant sudo ALL, a
shell, apt, systemctl, or wildcard command permissions.
Generate the key locally. Keep its private half outside this repository with
mode 0600; verify the target's SSH host key by an independent channel before
adding it to known_hosts. Do not weaken StrictHostKeyChecking.
## Configure OpenClaw
Copy the structure in examples/openclaw-plugin-config.example.json into the
local, private OpenClaw configuration under
plugins.entries.tfg-linux-diagnostics.config. Replace every placeholder with
the deployment's own values. Do not commit the real configuration.
Merge the restrictive tools section from examples/openclaw-tools.example.json
into the same private configuration. The intended policy exposes only
linux_diagnostic and keeps elevated tools disabled.
Install from a local checkout during development:
openclaw plugins install --link ./
openclaw plugins enable tfg-linux-diagnostics
openclaw config validate
openclaw gateway restart
openclaw plugins inspect tfg-linux-diagnostics --runtime --json
This repository is source-first. Build it locally before linking it; do not use
the direct Git installer unless a later release explicitly ships a reviewed
package artifact containing dist/.
## Workspace files
Copy the active Markdown files from workspace/ into the OpenClaw agent
workspace: AGENTS.md, TOOLS.md, SOUL.md, IDENTITY.md, and HEARTBEAT.md. They
define the behavioural contract and legal warning; they do not replace technical
controls.
Do not copy USER.md from another operator and do not enable a generic
BOOTSTRAP.md for this prototype.
## Add a diagnostic safely
Adding a diagnostic changes the threat model. Before exposing one:
1. Define a closed tool input schema; never accept a command, host, path, or
arbitrary service name.
2. Add a fixed command template in the plugin and a root-owned read-only script
on Debian.
3. Add one exact sudoers rule and one dispatcher branch.
4. Add unit and negative tests for allowed and rejected inputs.
5. Review the model-facing tool surface, revalidate the plugin and perform a
focused security regression.
## Limitations
This is an experimental academic prototype for a controlled laboratory. It
supports diagnosis only, not remediation. AI output can be wrong or incomplete;
an operator must validate every interpretation and carry out any recommended
action manually. It is not a production security audit or an operational
automation system.
## License
This project is licensed under the MIT License. This allows use, modification,
redistribution and commercial use, provided the copyright and license notice are
preserved. Dependencies and external services retain their own licenses and
terms.
tools
Comments
Sign in to leave a comment