feat(agents): add email-security-analyst NAT plugin

[nv-odrulea]

Summary

• Adds email-security-analyst as a new NAT tool_calling_agent example with 11 capability tools: triage, severity assessment, attack attribution, IOC extraction, header analysis, URL brand-impersonation checking, incident response, and warning drafting
• Each tool owns its first-line output contract; return_direct ends the graph on the tool result, making deterministic metrics possible
• Prompt injection defenses on every capability prompt via a shared _guardrail() builder
• 60s timeout on LLM invocations via asyncio.wait_for
• Registers in plugins/nemo-agents/pyproject.toml as a workspace package

Summary by CodeRabbit

• New Features

  • Added an email security analyst example with workflows for message review, triage, severity assessment, attack attribution, thread tracing, header and URL analysis, incident response, and warning drafting.
  • Added automatic extraction and normalization of URLs and domains from email content.
  • Added support for registering and running the example through the agent framework.

• Tests

  • Added coverage for indicator extraction, deduplication, sorting, normalization, and edge cases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f0ad4fd7-8bd3-4b3d-acfd-4941fd2c7a66

📥 Commits

Reviewing files that changed from the base of the PR and between 5da928b and eac2701.

📒 Files selected for processing (1)

• plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/email-security-analyst-agent.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/email-security-analyst-agent.yml

---

📝 Walkthrough

Walkthrough

Adds a packaged email security analyst example. The example registers guarded LLM-backed analysis tools, a direct-return workflow, deterministic IOC extraction, tests, and uv workspace integration.

Changes

Email security analyst

Layer / File(s)	Summary
Package and workspace integration plugins/nemo-agents/examples/email-security-analyst/pyproject.toml, plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/__init__.py, plugins/nemo-agents/pyproject.toml, pyproject.toml	Adds Hatch package metadata, the nat.components entry point, license headers, dependency sources, and uv workspace membership.
Agent workflow and analysis tools plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/prompt.py, plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/register.py, plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/email-security-analyst-agent.yml	Adds prompt-injection guardrails, ten prompt-backed analysis tools, deterministic IOC registration, shared LLM invocation with timeout handling, and a direct-return tool-calling workflow.
Deterministic IOC extraction plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/utils.py, plugins/nemo-agents/examples/email-security-analyst/tests/test_extract_iocs.py, plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/register.py	Adds URL and domain extraction with normalization, sorting, and deduplication. Registers the IOC tool and tests extraction behavior.

Sequence Diagram(s)

sequenceDiagram
  participant Analyst
  participant DirectReturnWorkflow
  participant RegisteredTool
  participant _invoke_llm
  participant ConfiguredLLM
  Analyst->>DirectReturnWorkflow: email security request
  DirectReturnWorkflow->>RegisteredTool: selected capability and email content
  RegisteredTool->>_invoke_llm: prompt with body
  _invoke_llm->>ConfiguredLLM: invoke with timeout
  ConfiguredLLM-->>_invoke_llm: response content
  _invoke_llm-->>RegisteredTool: analysis result
  RegisteredTool-->>DirectReturnWorkflow: tool result
  DirectReturnWorkflow-->>Analyst: direct response

Loading

Suggested reviewers: tylersbray

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the addition of the email-security-analyst NAT plugin.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch od/email-security-analyst-plugin

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/email-security-analyst-agent.yml`:
- Around line 134-137: Update the input-routing instructions in the email
security analyst configuration to remove the non-JSON path that derives an
analyst question or tool selection from unstructured input. Either reject
non-JSON input or treat it solely as untrusted evidence routed to
review_messages, without deriving tool arguments from it; preserve the existing
JSON handling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d6fbe2d1-7975-4803-80b9-ea709106d3fc

📥 Commits

Reviewing files that changed from the base of the PR and between 79ca283 and 5da928b.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

• plugins/nemo-agents/examples/email-security-analyst/pyproject.toml
• plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/__init__.py
• plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/email-security-analyst-agent.yml
• plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/prompt.py
• plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/register.py
• plugins/nemo-agents/examples/email-security-analyst/src/nat_email_security_analyst/utils.py
• plugins/nemo-agents/examples/email-security-analyst/tests/test_extract_iocs.py
• plugins/nemo-agents/pyproject.toml
• pyproject.toml

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	30257/38273	79.1%	63.7%
Integration Tests	N/A	N/A	N/A

[walston]

LG2M