Version Support Policy:

ProjectHermes is in active development (pre-v1.0). We recommend always running the latest commit from the main branch to receive the most up-to-date security fixes and improvements. Once we reach v1.0, we will provide a more detailed long-term support (LTS) policy.

Do not open public issues for security vulnerabilities.

We take security seriously. If you discover a security vulnerability, please report it responsibly.

Send an email to: 4211002+mvillmow@users.noreply.github.com

Or use the GitHub private vulnerability reporting feature if available.

Please include as much of the following information as possible:

• Description - Clear description of the vulnerability
• Impact - Potential impact and severity assessment
• Steps to reproduce - Detailed steps to reproduce the issue
• Affected files - Which source files, endpoints, or configurations are affected
• Suggested fix - If you have a suggested fix or mitigation

Subject: [SECURITY] Webhook registration accepts arbitrary callback URLs (SSRF)

Description:
The /webhooks/register endpoint does not validate callback URLs,
allowing an attacker to register webhooks pointing to internal services
and use Hermes as a Server-Side Request Forgery (SSRF) proxy.

Impact:
An attacker could probe internal services, access metadata endpoints,
or exfiltrate data via outbound webhook calls.

Steps to Reproduce:
1. POST /webhooks/register with callback_url="http://169.254.169.254/metadata"
2. Trigger the webhook event
3. Observe Hermes makes requests to the internal metadata endpoint

Affected Files:
src/hermes/routes.py (webhook registration handler)

Suggested Fix:
Validate callback URLs against an allowlist of permitted domains/schemes.

We aim to respond to security reports within the following timeframes:

We use the following severity levels:

If a WEBHOOK_SECRET is compromised or needs to be rotated, follow these steps:

1. Generate a new secret

   openssl rand -hex 32

2. Update the deployment environment Set the new value in your deployment environment (e.g. update the WEBHOOK_SECRET variable in your .env file, secrets manager, or container orchestration platform).

3. Restart the service

   just start
   # or, in Docker:
   docker compose up --build -d

4. Verify the service is healthy

   just health

   The /health endpoint should return {"status": "ok"} with a 200 response.

5. Update the secret in external services Reconfigure each external service (GitHub, Slack, etc.) that sends signed webhook payloads to use the new secret. Until this is done, those webhooks will be rejected with a 401 Unauthorized response.

We follow responsible disclosure practices:

1. Report privately - Do not disclose publicly until a fix is available
2. Allow reasonable time - Give us time to investigate and develop a fix
3. Coordinate disclosure - We will work with you on disclosure timing
4. Credit - We will credit you in the security advisory (if desired)

When you report a vulnerability:

1. Acknowledge receipt within 48 hours
2. Investigate and validate the report
3. Develop and test a fix
4. Release the fix
5. Publish a security advisory

• Python FastAPI source code and route handlers
• Webhook registration and delivery logic
• NATS client configuration and subject routing
• Dockerfile and container configuration
• Environment configuration (.env)

• NATS server itself (report to nats-io)
• Odysseus meta-repo (report to Odysseus)
• Other HomericIntelligence submodule repos (report to that repo directly)
• Social engineering attacks
• Physical security

When contributing to ProjectHermes:

• Validate all webhook callback URLs against an allowlist
• Authenticate webhook senders using signatures or shared secrets
• Never log sensitive payload data or credentials
• Use environment variables for NATS and external service credentials
• Sanitize all external input before publishing to NATS subjects

For security-related questions that are not vulnerability reports:

• Open a GitHub Discussion with the "security" tag
• Email: 4211002+mvillmow@users.noreply.github.com

Thank you for helping keep HomericIntelligence secure!