appium-guardrail-express

🛡️ Input guardrail middleware & REST API for Appium mobile automation safety.

Classifies automation instructions as ALLOW / BLOCK / WARN using a rule engine with LLM fallback (Groq API).

Features

• Express Middleware — drop into any Express app with createGuardrailMiddleware()
• REST API — standalone server with evaluate, classify, and rules CRUD endpoints
• Rule Engine — keyword & regex pattern matching for fast, deterministic classification
• LLM Fallback — semantic classification via Groq API when no rules match
• 3 Middleware Modes — block (403 on danger), warn (log + pass), passthrough (informational)
• Runtime Rule Management — add/remove rules via API without restart
• CLI — npx appium-guardrail-express --port 3000
• Zero Config — works out of the box with sensible defaults

Installation

npm install appium-guardrail-express

Quick Start

1. As Express Middleware

const express = require("express");
const { createGuardrailMiddleware } = require("appium-guardrail-express");

const app = express();
app.use(express.json());

// Block mode: returns 403 if dangerous steps detected
app.use("/automate", createGuardrailMiddleware({ mode: "block" }));

app.post("/automate", (req, res) => {
  // Only reaches here if all steps are safe
  res.json({ status: "executing", guardrail: req.guardrail });
});

app.listen(3000);

2. As Standalone API Server

const { createServer } = require("appium-guardrail-express");

const { app } = createServer({ useLLMFallback: true });
app.listen(3000, () => console.log("Guardrail API running on :3000"));

3. Via CLI

# Start the server
npx appium-guardrail-express --port 3000

# With options
npx appium-guardrail-express --port 8080 --rules ./my-rules.json --no-llm

4. Programmatic (No Express)

const { AppiumGuardrail } = require("appium-guardrail-express");

const guardrail = new AppiumGuardrail({ useLLMFallback: true });

const result = await guardrail.evaluate([
  { id: "1", instruction: "open settings" },
  { id: "2", instruction: "turn off wifi" },
]);

console.log(result.safe);       // false
console.log(result.summary);    // { total: 2, allowed: 1, blocked: 1, warned: 0 }

API Endpoints

GET /api/v1/health

Server health check.

POST /api/v1/evaluate

Evaluate a batch of steps.

curl -X POST http://localhost:3000/api/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "id": "1", "instruction": "open settings" },
      { "id": "2", "instruction": "toggle wifi off" },
      { "id": "3", "instruction": "swipe up on screen" }
    ]
  }'

Response:

{
  "summary": { "total": 3, "allowed": 2, "blocked": 1, "warned": 0 },
  "results": [
    { "id": "1", "instruction": "open settings", "action": "ALLOW", "source": "RULE_ENGINE" },
    { "id": "2", "instruction": "toggle wifi off", "action": "BLOCK", "source": "RULE_ENGINE" },
    { "id": "3", "instruction": "swipe up on screen", "action": "ALLOW", "source": "RULE_ENGINE" }
  ],
  "safe": false
}

POST /api/v1/classify

Classify a single instruction.

curl -X POST http://localhost:3000/api/v1/classify \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "enable airplane mode" }'

GET /api/v1/rules

List all loaded rules.

POST /api/v1/rules

Add a new rule at runtime.

curl -X POST http://localhost:3000/api/v1/rules \
  -H "Content-Type: application/json" \
  -d '{
    "id": "block-custom",
    "description": "Block custom action",
    "action": "BLOCK",
    "keywords": ["custom dangerous action"]
  }'

DELETE /api/v1/rules/:id

Remove a rule by ID.

Middleware Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | mode | "block" \| "warn" \| "passthrough" | "block" | How to handle dangerous steps | | rulesPath | string | built-in rules | Path to custom rules JSON | | useLLMFallback | boolean | true | Use Groq LLM when no rule matches | | inputField | string | "steps" | Field name in req.body for steps array |

Environment Variables

| Variable | Description | |----------|-------------| | GROQ_KEY or GROQ_API_KEY | Groq API key for LLM fallback | | GROQ_MODEL | Override LLM model (default: llama-3.3-70b-versatile) | | PORT | Server port (default: 3000) |

Default Rules

The package ships with rules that block:

• 🚫 WiFi / mobile data toggling
• 🚫 Airplane mode activation
• 🚫 Developer mode / USB debugging disable
• 🚫 Bluetooth disable
• 🚫 Factory reset / device wipe
• 🚫 Power off / shutdown

And allow:

• ✅ Opening apps and settings
• ✅ Screen navigation (swipe, scroll, tap)
• ✅ Normal UI interactions

Custom Rules Format

{
  "version": "1.0.0",
  "rules": [
    {
      "id": "block-wifi-off",
      "description": "Block turning off WiFi",
      "action": "BLOCK",
      "keywords": ["off wifi", "disable wifi", "turn off wifi"],
      "patterns": ["\\b(off|disable)\\b.*\\bwifi\\b"]
    }
  ]
}

Testing

npm test

License

MIT