Tool Flower 🌸

Secure automation control plane for running operational tools locally or over SSH with policy enforcement, audit logging, and execution observability.

Architecture

The system follows a control-plane architecture:

• Frontend: static UI pages in public/ (execution history, detail, run UI)
• API service: Express app in server/ (auth, validation, queueing, audit)
• Worker: async worker loop (server/worker.js) claims executions and runs them
• Persistence: PostgreSQL stores users, tools, ssh targets, executions, logs, and audit events

Quick view: Client → API → PostgreSQL Queue → Worker → Execution Logs → UI

See the visual architecture above and additional detail in docs/architecture.md.

Core Features

• Secure command execution using predefined tool templates and fixed args
• Template-based parameter schemas with typed validation before queueing
• Async worker execution model (DB-backed queue, FOR UPDATE SKIP LOCKED row claims)
• PostgreSQL persistence for durable executions, logs, and audit events
• Execution lifecycle tracking and per-execution log streaming
• Execution history UI with filtering, sorting, and execution details
• Role-Based Access Control (viewer, operator, admin) enforced by API
• SSH execution targets with trusted-host allowlist and known-hosts verification
• Audit logging for user actions and execution events
• Observability endpoints (execution logs, audit stream, metrics summary)

Execution Lifecycle

Execution lifecycle:

queued
	↓
running
	↓
succeeded | failed | timed_out

• A client enqueues an execution via the API after template validation.
• The worker polls the DB, claims a queued row (FOR UPDATE SKIP LOCKED), and runs the tool (local spawn or SSH).
• Worker streams stdout/stderr into execution_logs, updates executions status and timestamps, and emits audit events.

Security Model

Layered protections are applied before and during execution:

• Command templates limit allowed binaries and fixed args; tools declare a param_schema.
• Typed argument validation prevents injection and enforces shapes and types.
• RBAC restricts which roles can run which tools and view results.
• SSH allowlist (TRUSTED_SSH_HOSTS) and ssh_known_hosts are used for remote execution safety.
• Execution limits: per-tool timeout_ms and max_output_bytes are enforced at runtime.
• All operations and important state changes emit audit_events for traceability.

See docs/security-model.md for full details.

Project Structure

Tool_Flower/
├─ apps/                 # (optional) future UI or micro frontends
├─ services/             # (optional) service-level components
├─ packages/             # (optional) shared packages
├─ server/               # API, worker, config, migrations, seeds, tests
├─ public/               # static frontend pages (execution-history, detail, run)
├─ docs/                 # architecture, security, runbook, API
└─ tests/                # automated tests and integration specs

• server/ contains app.js, server.js, worker.js, execution.js, validation.js, DB migrations and seeds.
• public/ contains the execution history/detail UI and scripts that call the API.

Running Locally

Prerequisites:

• Node.js (14+)
• npm
• PostgreSQL (local or remote)

Quick start (developer mode):

git clone <repo-url>
cd Tool_Flower
npm install
cd server
npm install
# create and seed the database (see server/migrations and server/seeds)
# set required env vars (example below)
npm run dev

Important environment variables (defaults in server/config.js):

• DATABASE_URL — PostgreSQL connection string (default: postgresql://toolflower:toolflower@localhost:5432/toolflower)
• PORT — API port (default: 3000)
• TRUSTED_SSH_HOSTS — comma-separated allowlist for SSH targets
• SSH_KNOWN_HOSTS_FILE — path to known_hosts (defaults to ~/.ssh/known_hosts)
• SSH_PRIVATE_KEY_PATH — path to SSH private key for worker
• ALLOW_LOCAL_EXECUTION / ALLOW_SSH_EXECUTION — toggles for execution types

The project includes DB migrations (server/migrations/) and a basic seed (server/seeds/001_seed.sql) that creates an initial user and ssh target for development.

Key Documentation

Document	Description
docs/architecture.md	System architecture and component boundaries
docs/api.md	REST API reference
docs/security-model.md	Execution security model
docs/execution-runbook.md	Operational debugging guide

Additional docs: docs/setup.md, docs/development.md, docs/operations.md, docs/performance.md

Demo

Execution history view:

Execution detail timeline:

CI / Quality

• Prettier for formatting
• ESLint for linting
• GitHub Actions CI runs formatting and tests (server-quality)

Future Improvements

• Scheduled and recurring jobs
• Multi-tenant access controls and namespaces
• Plugin ecosystem for custom tool types
• Rich execution dashboards and alerting
• Webhooks and external integrations

Example Execution Flow

1. Operator selects a tool from the UI
2. API validates parameters and permissions
3. Execution is queued in PostgreSQL
4. Worker claims the job
5. Tool executes locally or over SSH
6. Logs stream into execution_logs
7. UI displays execution history and results

Why This Project Exists

Tool Flower is a compact, production-minded example of secure operational tooling. It's designed to showcase:

• backend engineering skills (APIs, DB schema, worker design)
• distributed system thinking (DB-backed queues, idempotency, retries)
• secure command execution patterns (templates, validation, RBAC)
• operational concerns (audit, observability, runbooks)

This repository is suitable for interview demos, portfolio reviews, and as a starting point for building safer operator tooling.

---

For more details see the docs/ folder and the server/ source.

License: MIT