The trust boundary
-Flowlight plugins are scoped to HTTPS inspection. They run after a request and response have already been captured, redacted, clipped, attributed to an app or agent, and written to the local database. A plugin can add findings and suggest ordinary Flowlight guardrails, but it does not block, rewrite, mock, or transform traffic by itself.
+Flowlight plugins are scoped to HTTPS inspection. They run after a request and response have already been captured, redacted, clipped, attributed to an app or agent, and written to the local database. A plugin can add findings and suggest ordinary Flowlight guardrails or rules for the user to apply, but it does not block, rewrite, mock, or transform traffic by itself.
Flowlight reviews a plugin package before installation. The review shows provenance, signature status, permissions, privacy categories, package digest and script digest. Package import fails closed when a signed package is malformed or tampered with; runtime JavaScript still fails open so capture remains complete.
Manifest
@@ -114,6 +114,7 @@Provenance and package review
Findings
A JavaScript plugin defines a synchronous evaluate(context) function. Flowlight passes context.manifest and a sanitized context.exchange containing only the metadata families declared in permissions. Scripts run out of process with an empty environment, a 128 KB script limit and a short timeout; failures produce no findings.
A finding is a bounded record attached to one inspected exchange. Evidence should name facts, not leak content: method, host, redacted path shape, byte counts, header names, model provider, tool names, MCP server names, approval mode and policy labels. Do not store header values, raw bodies, credentials, full tool inputs, prompts, completions or unredacted query strings.
+When a manifest declares the suggestGuardrail capability and permission, a finding can also include a suggestedGuardrail or suggestedRule. Flowlight stores those as inert suggestions; the Inspect view saves them only when the user clicks the normal Add action.
{
"severity": "medium",
"title": "High-risk tool available",
@@ -127,6 +128,15 @@ Findings
"server": "",
"tool": "Bash",
"origin": "observed"
+ },
+ "suggestedRule": {
+ "action": "block",
+ "app": "claude",
+ "destination": "api.example.com",
+ "path": "/v1/messages",
+ "method": "POST",
+ "status": 403,
+ "name": "Review Claude API traffic"
}
}
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index 7dac548..076d0e9 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -3,7 +3,7 @@
Write inspection plugins
The trust boundary
-Flowlight plugins are scoped to HTTPS inspection. They run after a request and response have already been captured, redacted, clipped, attributed to an app or agent, and written to the local database. A plugin can add findings and suggest ordinary Flowlight guardrails, but it does not block, rewrite, mock, or transform traffic by itself.
+Flowlight plugins are scoped to HTTPS inspection. They run after a request and response have already been captured, redacted, clipped, attributed to an app or agent, and written to the local database. A plugin can add findings and suggest ordinary Flowlight guardrails or rules for the user to apply, but it does not block, rewrite, mock, or transform traffic by itself.
Flowlight reviews a plugin package before installation. The review shows provenance, signature status, permissions, privacy categories, package digest and script digest. Package import fails closed when a signed package is malformed or tampered with; runtime JavaScript still fails open so capture remains complete.
Manifest
@@ -66,6 +66,7 @@Provenance and package review
Findings
A JavaScript plugin defines a synchronous evaluate(context) function. Flowlight passes context.manifest and a sanitized context.exchange containing only the metadata families declared in permissions. Scripts run out of process with an empty environment, a 128 KB script limit and a short timeout; failures produce no findings.
A finding is a bounded record attached to one inspected exchange. Evidence should name facts, not leak content: method, host, redacted path shape, byte counts, header names, model provider, tool names, MCP server names, approval mode and policy labels. Do not store header values, raw bodies, credentials, full tool inputs, prompts, completions or unredacted query strings.
+When a manifest declares the suggestGuardrail capability and permission, a finding can also include a suggestedGuardrail or suggestedRule. Flowlight stores those as inert suggestions; the Inspect view saves them only when the user clicks the normal Add action.
{
"severity": "medium",
"title": "High-risk tool available",
@@ -79,6 +80,15 @@ Findings
"server": "",
"tool": "Bash",
"origin": "observed"
+ },
+ "suggestedRule": {
+ "action": "block",
+ "app": "claude",
+ "destination": "api.example.com",
+ "path": "/v1/messages",
+ "method": "POST",
+ "status": 403,
+ "name": "Review Claude API traffic"
}
}
diff --git a/templates/inspection-plugin/README.md b/templates/inspection-plugin/README.md
index 9fc6aa9..b06dd4d 100644
--- a/templates/inspection-plugin/README.md
+++ b/templates/inspection-plugin/README.md
@@ -4,7 +4,7 @@ This template describes an advisory Flowlight inspection plugin package. Flowlig
## Trust boundary
-Plugins run after an inspected HTTP exchange has been recorded locally. They can add findings and suggest normal Flowlight guardrails, but they do not block, rewrite, mock, transform, upload, or export traffic by themselves.
+Plugins run after an inspected HTTP exchange has been recorded locally. They can add findings and suggest normal Flowlight guardrails or rules for the user to apply, but they do not block, rewrite, mock, transform, upload, or export traffic by themselves.
Evidence must be bounded and redacted. Do not include raw request or response bodies, prompts, completions, header values, credentials, full tool inputs, or unredacted query strings.
@@ -20,7 +20,7 @@ Evidence must be bounded and redacted. Do not include raw request or response bo
Define a synchronous `evaluate(context)` function. Flowlight passes `context.manifest` and `context.exchange`; the exchange contains only the sanitized metadata allowed by the plugin's declared permissions. It never contains request bodies, response bodies, header values, prompts, completions or full tool inputs.
-Return up to 8 findings. Each finding uses `severity`, `title`, `summary`, bounded `evidence`, and an optional `suggestedGuardrail` with `agent`, `server`, `tool` or `resource`. Scripts run out of process with an empty environment, a 128 KB script limit and a short timeout. Failures produce no findings.
+Return up to 8 findings. Each finding uses `severity`, `title`, `summary`, bounded `evidence`, and optional suggestions. `suggestedGuardrail` can name `agent`, `server`, `tool` or `resource`; `suggestedRule` can name a normal Flowlight `block` or `allow` rule with `app`, `destination`, `path`, `method`, `status` and `name`. Suggestions appear as user-reviewed actions and require the `suggestGuardrail` capability and permission. Scripts run out of process with an empty environment, a 128 KB script limit and a short timeout. Failures produce no findings.
## Files
diff --git a/templates/inspection-plugin/findings.example.json b/templates/inspection-plugin/findings.example.json
index 4301147..a673bb4 100644
--- a/templates/inspection-plugin/findings.example.json
+++ b/templates/inspection-plugin/findings.example.json
@@ -22,6 +22,15 @@
{ "label": "Provider", "value": "Anthropic" },
{ "label": "Connector", "value": "github" },
{ "label": "Approval", "value": "always" }
- ]
+ ],
+ "suggestedRule": {
+ "action": "block",
+ "app": "claude",
+ "destination": "api.github.com",
+ "path": "",
+ "method": "",
+ "status": 403,
+ "name": "Review provider connector traffic"
+ }
}
]
diff --git a/templates/inspection-plugin/validate.js b/templates/inspection-plugin/validate.js
index 5cb4dc3..8df6b36 100644
--- a/templates/inspection-plugin/validate.js
+++ b/templates/inspection-plugin/validate.js
@@ -98,6 +98,17 @@ function checkFindings(findings, source = 'findings') {
requireCondition((evidence.label || '').length <= 80, `${source} ${index} evidence label is too long`);
requireCondition((evidence.value || '').length <= 240, `${source} ${index} evidence value is too long`);
});
+ if (finding.suggestedRule !== undefined) {
+ requireCondition(isPlainObject(finding.suggestedRule), `${source} ${index} suggestedRule must be an object`);
+ requireCondition(['block', 'allow'].includes(finding.suggestedRule.action || 'block'), `${source} ${index} suggestedRule action must be block or allow`);
+ requireCondition((finding.suggestedRule.app || finding.suggestedRule.destination), `${source} ${index} suggestedRule must name an app or destination`);
+ for (const key of ['app', 'destination', 'path', 'method', 'name']) {
+ requireCondition(typeof (finding.suggestedRule[key] || '') === 'string', `${source} ${index} suggestedRule ${key} must be a string`);
+ }
+ if (finding.suggestedRule.status !== undefined) {
+ requireCondition(Number.isInteger(finding.suggestedRule.status) && finding.suggestedRule.status >= 400 && finding.suggestedRule.status <= 599, `${source} ${index} suggestedRule status must be 400-599`);
+ }
+ }
});
}