feat(security): add container image scanner plugin with Trivy/Grype integration (#2216)

[kamath-a]

🧱 New Plugin

🔗 Closes

Closes #2216

🚀 Summary

Scans container images for CVEs using Trivy or Grype before they are registered or deployed through the gateway, blocking or auditing based on configurable severity policy.

Included:

• Scanner CLI integration: async subprocess wrappers for Trivy and Grype, JSON output parsing, timeout and error handling
• Policy engine: severity threshold filtering, CVE ignore list, enforce/audit/disabled modes with block decision and human-readable violation reason
• Cache layer: digest-keyed TTL cache, policy re-evaluated on every hit so threshold changes apply without re-scanning, skipped when no digest is available
• Storage layer: currently implemented with dictionaries, bounded in-memory ScanResultRepository with LRU eviction, shared module-level singleton used by both plugin and REST router
• Registry auth: per-registry credential resolution from environment variables at scan time, token and basic auth support, injected into scanner subprocess environment
• FastAPI router (mcpgateway/routers/container_scanner_router.py): health endpoint, scan list with most-recent-first ordering, per-image lookup by ref or digest, full vulnerabilities[] array with fixed_version and description in response
• Admin UI: scan results table with expandable rows showing per-CVE severity, installed version, fixed version and description, scan error surfaced inline, accessible via Extensions > Container Scanner in sidebar
• Plugin orchestration (container_scanner.py): full pipeline: cache → auth → scanner → policy → persist, graceful fail_open/fail_closed error handling, PluginViolation construction on block
• Hook integration (mcpgateway/plugins/framework/hooks/gateway.py): server_pre_register and runtime_pre_deploy hook types with ServerPreRegisterPayload / RuntimePreDeployPayload, registered into global hook registry on module import

Testing

Unit tests (109 passed)
Cover each component in isolation with all external calls mocked:

• test_container_scanner.py: scan() pipeline: disabled mode, cache hits/misses, error handling (fail_open/fail_closed), result structure and summary counts
• test_repository.py: save/get round-trips, overwrite behaviour, LRU eviction, capacity limits, clear()
• test_trivy_runner.py: JSON parsing, severity normalisation, empty/missing fields, timeout and non-zero exit errors
• test_grype_runner.py: same for Grype's fix.state/versions schema, invalid severity filtering, auth env passthrough
• test_policy_evaluator.py: threshold filtering, ignore list, fail_on_unfixed, enforce vs audit modes
• test_cache_manager.py: TTL expiry, cache miss, disabled cache
• test_config.py: ScannerConfig validation, registry auth field rules

pytest tests/unit/plugins/test_container_scanner/ -v

Integration tests (18 passed)
Covers 2 end-to-end scenarios with real policy/repository/evaluator, and scanner CLI mocked:
test_api.py: health endpoint empty/populated state, scan list ordering (most-recent-first), per-image lookup by ref and digest, 404 on unknown image, unauthenticated requests rejected
test_hook_pipeline.py: hook fires and result stored in shared singleton, blocked/unblocked results reflected correctly in API response, disabled mode skips runner and stores no result, CRITICAL vuln triggers block with PluginViolation, unblocked result has continue_processing=True

pytest tests/integration/test_container_scanner/ -v

🧪 Checks

• Plugin was bootstrapped with the CLI (native or external template)
• Unit tests created for the new plugin
• make lint plugins passes
• make test passes
• CHANGELOG updated (if user-facing)
• README documentation was created for the plugin
• New plugin added to the documentation linking to the README above

[crivetimihai]

Thanks @kamath-a. Strong implementation with excellent test coverage (109 unit + 18 integration). However, this PR modifies 10 core gateway files (main.py, admin.py, framework hooks, new router, templates) — a plugin should be self-contained within plugins/container_scanner/ and use the existing hook framework without modifying it. With #3754 migrating to CPEX, this should be reworked as an external plugin. Note: #3658 appears to contain identical code — please confirm which PR should be the active one. Happy to discuss the plugin boundary design.

[kamath-a]

Hi @crivetimihai, apologies for the late response, and thank you so much for the feedback! This is indeed the active PR, #3658 is now outdated. I have looked into some of the other plugins and their structures, and from my understanding, the following changes are required:

• plugin-manifest.yaml in the container_scanner folder
• Use @hook to define a new hook, along with newly defined classes for payload and result, as per pattern 3 in plugins/README.md
• a server.py file, the FastMCP server that exposes the tools
• a separate UI rather than the embedded one I have implemented here

Please let me know if I have misunderstood or omitted anything! Thanks again!

[araujof]

DO NOT MERGE before #3754 is merged.
Modifies deleted framework/init.py, adds hooks/gateway.py

[cafalchio]

Hi @kamath-a Could you rebase this PR. The plugin framework was transformed into a python package. These imports now would import from cpex.
from cpex.framework import PluginPayload, PluginResult

[jonpspri]

Closing because the linked issue #2216 ([FEATURE][SECURITY]: Container vulnerability scanner — Trivy/Grype integration) was closed as NOT_PLANNED. The feature has been explicitly declined; this PR no longer has a merge target.