Add documentation for threat detection

Author: jrpbc

docs/infra/threat-detection.md

@@ -0,0 +1,102 @@
+# Threat Detection (AWS GuardDuty)
+
+The infrastructure includes AWS GuardDuty for comprehensive threat detection and security monitoring across the AWS account. This document describes how GuardDuty is configured, its capabilities, and troubleshooting procedures.
+
+## How threat detection works
+
+GuardDuty analyzes tens of billions of events across multiple AWS data sources to detect malicious activity and unauthorized behavior:
+
+- **AWS CloudTrail event logs** - API calls and user activities
+- **Amazon VPC Flow Logs** - Network traffic patterns
+- **DNS logs** - Domain name resolution requests
+- **S3 data events** - Object-level operations for malware detection
+
+GuardDuty uses machine learning, anomaly detection, and integrated threat intelligence to identify threats including:
+
+- Compromised instances communicating with malicious IPs
+- Cryptocurrency mining activities
+- Data exfiltration attempts
+- Malware in S3 objects
+- Reconnaissance attacks
+- Unusual API call patterns
+
+## Malware detection for S3 storage
+
+GuardDuty's malware detection feature continuously scans files uploaded to S3 buckets for malicious content. When malware is detected:
+
+1. **File access is blocked** - Downloads of infected files are prevented
+2. **Findings are generated** - Security findings are created in the GuardDuty service with detailed information including:
+   - **Finding ID** - Unique identifier for the security event
+   - **Severity level** - Low, Medium, High, Critical
+   - **Finding type** - Specific threat classification (e.g., `Malware:S3/MaliciousFile`)
+   - **Resource details** - Affected S3 bucket, object key, and account information
+   - **Timestamp** - When the malware was detected
+   - **Evidence** - Technical details about the malicious content
+   - **Remediation** - Recommended actions to address the threat
+3. **Tags are applied** - S3 objects are tagged with scan results for tracking:
+   - **`GuardDutyMalwareScanStatus`** - Scan result status (`NO_THREATS_FOUND`, `THREATS_FOUND`)
+
+### Checking S3 Object Tags for Malware Status
+
+```bash
+#!/bin/bash
+
+for plan_id in $(aws guardduty list-malware-protection-plans \
+    --query "MalwareProtectionPlans[*].MalwareProtectionPlanId" \
+    --output text); do
+
+    bucket=$(aws guardduty get-malware-protection-plan \
+        --malware-protection-plan-id "$plan_id" \
+        --query "ProtectedResource.S3Bucket.BucketName" \
+        --output text 2>/dev/null)
+
+    if [ "$bucket" != "None" ] && [ -n "$bucket" ]; then
+        echo "Scanning protected bucket: $bucket ..."
+
+        aws s3api list-objects-v2 --bucket "$bucket" \
+            --query "Contents[*].Key" \
+            --output text 2>/dev/null | tr '\t' '\n' | \
+        while read -r key; do
+            if [ -n "$key" ]; then
+                tags=$(aws s3api get-object-tagging \
+                    --bucket "$bucket" \
+                    --key "$key" \
+                    --query "TagSet[?Key=='GuardDutyMalwareScanStatus' && Value=='THREATS_FOUND'].Value" \
+                    --output text 2>/dev/null)
+
+                if [ "$tags" = "THREATS_FOUND" ]; then
+                    echo "MALWARE DETECTED: s3://$bucket/$key"
+                fi
+            fi
+        done
+    fi
+done
+```
+
+### Accessing GuardDuty Findings
+
+**AWS Console:**
+- Navigate to GuardDuty Console → Findings
+- Filter by finding type, severity, or resource
+- View detailed finding information and evidence
+
+## Deployment
+
+GuardDuty is deployed as part of the account layer infrastructure:
+
+```bash
+make infra-update-current-account
+```
+
+### Malware Detection Errors
+
+When GuardDuty detects malware in uploaded files, users may encounter the following errors:
+
+#### File Download Blocked
+
+**Error Message:**
+```
+fatal error: An error occurred (403) when calling the HeadObject operation: Forbidden
+```
+
+**Cause:** GuardDuty's malware detection has identified the file as containing malware or suspicious content, and AWS S3 is blocking access with a 403 Forbidden error.

docs/system-architecture.md

@@ -14,6 +14,7 @@ This diagram shows the system architecture. [🔒 Make a copy of this Lucid temp
 * **Cognito** — Amazon Cognito handles authentication and user management.
 * **Database Role Manager** — AWS Lambda serverless function that provisions the database roles needed by the application.
 * **GitHub** — Source code repository. Also responsible for Continuous Integration (CI) and Continuous Delivery (CD) workflows. GitHub Actions builds and deploys releases to an Amazon ECR registry that stores Docker container images for the application service.
+* **GuardDuty Threat Detection** — AWS GuardDuty continuously monitors for malicious activity and unauthorized behavior across the AWS account, analyzing CloudTrail events, VPC Flow Logs, and DNS logs to detect security threats and anomalous activities. Additionally provides malware detection for files uploaded to S3 storage, preventing infected files from being downloaded.
 * **Incident Management Service** — Incident management service (e.g. PagerDuty or Splunk On-Call) for managing on-call schedules and paging engineers for urgent production issues.
 * **NAT Gateway** — Enables outbound internet access for resources in private subnets.
 * **Secrets Manager** — Securely stores and retrieves sensitive information such as database credentials.