Skip to content

plugin-email.md

Latest commit

 

History

History
157 lines (117 loc) · 3.79 KB

plugin-email.md

File metadata and controls

157 lines (117 loc) · 3.79 KB
Raw

Plugin: plugin-email

Local email-header parsing and evidence-backed structural review.

Status:

Package: plugins/plugin-email
NPM name: @security-workbench/plugin-email
Quality: beta
Execution: local-only
Network: none
Persistence: none
External binaries: none
Implemented skills: 2
Owned workflows: 0

Purpose

plugin-email owns the email-header domain boundary:

raw RFC822-style header block
  → parse_email_headers
  → review_email_header

The parser normalizes observed header structure. The reviewer interprets those observations into evidence-backed routing, authentication-result, and identity-mismatch signals.

Implemented skills

Skill Category Purpose
parse_email_headers parser Parse an RFC822-style header block into normalized fields, duplicate-name observations, common identity fields, Received count, and Authentication-Results values.
review_email_header reviewer Review parsed header observations and emit evidence-backed local signals without DNS validation, content inspection, scoring, or phishing verdicts.

Boundary

This plugin remains local-only:

no network
no DNS lookup
no SPF/DKIM/DMARC/ARC/BIMI validation
no reputation lookup
no message-body or attachment inspection
no URL retrieval
no scoring
no findings
no phishing, spam, malicious, benign, delivered, or blocked verdicts

File reading is a CLI/API/UI adapter behavior. Skills receive bounded input from the runtime.

Input and output behavior

parse_email_headers

Input:

one bounded UTF-8 string containing an RFC822-style header block

Output includes:

normalized header records
header count
duplicate header names
From, To, Cc, Subject, Date, and Message-ID observations
Received count
Authentication-Results values
warnings

Header continuation lines are unfolded into the previous field. Malformed header lines and invalid field names fail clearly.

review_email_header

Accepted input:

parse_email_headers output object
JSON string containing parse_email_headers output
JSON string containing a full skill run result whose output is parse_email_headers output

Output includes:

source parser and warning count
header and duplicate-name observations
Received and Authentication-Results counts
From, To, Subject, Date, and Message-ID presence
Reply-To, Return-Path, Sender, and domain observations
observed authentication mechanisms and failure/error results
evidence records
signal records
explicit limitations

Shared primitives

Shared indicator and text utilities remain in core-utilities:

normalize_indicators
extract_urls
extract_emails
defang_iocs
refang_iocs

The email plugin does not duplicate those helpers and does not depend on sibling domain plugins.

Workflow status

Email-header review remains a recipe-level manual chain. No registered workflow is added by this package-boundary migration.

security-workbench skills run parse_email_headers \
  --input-file "$PWD/fixtures/email/auth-results-headers.txt" \
  > /tmp/email-headers.parsed.json

security-workbench skills run review_email_header \
  --input-file /tmp/email-headers.parsed.json \
  --format pretty

Plugin controls

The default profile enables the plugin. The minimal profile excludes it unless explicitly or persistently enabled.

security-workbench plugins describe plugin-email
security-workbench plugins disable plugin-email
security-workbench plugins reset plugin-email

Validation

pnpm --filter @security-workbench/plugin-email... build
pnpm --filter @security-workbench/plugin-email test
pnpm --filter @security-workbench/plugin-email typecheck:test

Repository-wide validation remains:

pnpm build
pnpm test
pnpm typecheck:test
./security-workbench-full-smoke.sh