Security Scanning with Shannon¶

Shannon is an autonomous AI-powered penetration tester that crawls and tests web applications for security vulnerabilities. This document covers how we use it for the rr-bizops project.

Running Shannon Locally¶

Prerequisites¶

Python 3.10+
Running Medusa backend on port 9000
Running storefront on port 8000 (optional, for storefront scanning)

Setup¶

Clone Shannon into the project directory (it's gitignored):

cd /Users/orther/code/rr-bizops
git clone https://github.com/tracecat-ai/shannon.git shannon/repo
cd shannon/repo
pip install -r requirements.txt  # or: pip install -e .

Running a scan¶

Make sure the dev environment is running first:

devenv up --detach
cd app && npm run dev

Then run Shannon against the local Medusa instance:

cd shannon/repo
python -m shannon \
  --config ../configs/medusa-local.yaml \
  --target http://localhost:9000 \
  --output ../results/

Results will be written to shannon/results/ (also gitignored).

Scanning the storefront¶

To scan the Next.js storefront separately, create a config targeting port 8000 or modify the target URL:

python -m shannon \
  --target http://localhost:8000 \
  --output ../results/storefront/

The storefront scan doesn't need authentication config since it's a public-facing site.

Weekly CI Scan¶

A GitHub Actions workflow runs Shannon automatically every Sunday at 3:00 AM UTC.

Workflow: .github/workflows/security-pentest.yml

How it works¶

Spins up PostgreSQL 16 and Redis 7 as service containers
Installs and builds the Medusa backend
Runs database migrations and seeds an admin user
Starts the Medusa server
Clones Shannon and runs it against the local Medusa instance
Uploads results as a GitHub Actions artifact (retained for 90 days)
Posts a summary to the GitHub Actions step summary

Manual triggers¶

You can trigger a scan manually from the Actions tab:

Go to Actions > Security Pentest (Shannon)
Click Run workflow
Choose the target environment and scan duration
Click Run workflow

Viewing results¶

Go to the completed workflow run in GitHub Actions
Download the shannon-pentest-results-N artifact
Extract and review the report files (JSON, HTML, or Markdown depending on Shannon's output format)

What Shannon Tests For¶

Shannon autonomously explores the application and tests for common web security vulnerabilities aligned with the OWASP Top 10:

OWASP Top 10 Coverage¶

Category	Description	Coverage
A01: Broken Access Control	IDOR, privilege escalation, missing auth checks	Tested - Shannon probes admin/store API boundaries
A02: Cryptographic Failures	Sensitive data exposure, weak crypto	Partial - checks for data in responses
A03: Injection	SQL injection, XSS, command injection	Tested - fuzzes input fields and API parameters
A04: Insecure Design	Business logic flaws	Tested - Shannon explores application flows autonomously
A05: Security Misconfiguration	Default configs, verbose errors, open endpoints	Tested - checks headers, error responses
A06: Vulnerable Components	Known CVE in dependencies	Not covered - use `npm audit` separately
A07: Auth Failures	Brute force, session management, weak passwords	Tested - probes login and session handling
A08: Data Integrity Failures	Deserialization, unsigned data	Partial
A09: Logging Failures	Insufficient logging	Not covered
A10: SSRF	Server-side request forgery	Tested where applicable

Project-Specific Focus Areas¶

The medusa-local.yaml config directs Shannon to focus on:

Store API (/store/*): Customer-facing endpoints including product browsing, cart operations, checkout flow, and compliance attestation
Admin API (/admin/*): Authentication, authorization boundaries, role-based access
Compliance endpoints (/store/compliance/*): COA access, purity records, RUO disclaimers

Safety Rules¶

The config prevents Shannon from:

Deleting products or orders (avoids data loss)
Deleting orders
Modifying payment provider settings

What Shannon Does NOT Cover¶

These areas require separate tooling or manual review:

Area	Why Not Covered	Alternative
Infrastructure security (NixOS, Caddy)	Shannon tests web apps, not OS/server config	Manual audit, Lynis, OpenSCAP
Network security	No network-layer scanning	nmap, Nessus
Dependency vulnerabilities	Shannon tests runtime behavior, not static deps	`npm audit`, Snyk, Dependabot
Container security	Docker image scanning is separate	Trivy, Grype
Secrets in code	Not a SAST tool	TruffleHog, GitLeaks
DNS/TLS configuration	Not in scope	SSLLabs, testssl.sh
Rate limiting validation	Limited coverage	Custom load testing (k6, artillery)
Business logic (deep)	AI coverage varies	Manual penetration testing

Recommended Complementary Tools¶

For comprehensive security coverage, pair Shannon with:

# Dependency audit
cd app && npm audit

# Secret scanning
trufflehog filesystem --directory=. --only-verified

# Container scanning (if building images locally)
trivy image ghcr.io/research-relay/rr-bizops/medusa:latest

# TLS configuration check (production)
testssl.sh https://api.research-relay.com

Interpreting Results¶

Severity Levels¶

Critical: Immediate action required. Data breach or full system compromise possible.
High: Fix before next release. Significant security impact.
Medium: Fix within current sprint. Limited but real impact.
Low: Track and fix opportunistically. Minimal direct impact.
Informational: No immediate risk but worth noting for defense-in-depth.

Common Findings and Response¶

Finding	Typical Response
Missing security headers	Add to Caddy config (`docs/dev/infrastructure-architecture.md`)
IDOR on admin endpoints	Fix access control in Medusa middleware
XSS in store responses	Sanitize output in API route handlers
Verbose error messages	Configure error handling for production mode
Session fixation	Review Medusa session/cookie configuration

False Positives¶

Shannon may flag:

CORS headers on API: Expected for the storefront-to-API communication
Admin panel accessible: Expected at /app -- it's protected by authentication
API version disclosure: MedusaJS includes version in responses by default

Document false positives in shannon/results/false-positives.md so they can be filtered in future runs.