# Datadog SCA GitHub Issue Creator Lambda

AWS Lambda function that automatically creates GitHub issues for third-party application dependency updates identified by Datadog Software Composition Analysis (SCA).

## Overview

This Lambda function:
- Receives Datadog SCA vulnerability findings via event payload
- Creates detailed GitHub issues with vulnerability information
- Assigns issues to GitHub Copilot for automated remediation
- Configures PR requirements (branch naming, commit message format)
- Provides clear acceptance criteria for dependency updates

## Event Payload Structure

The Lambda expects the following event payload:

```json
{
  "repository_name": "owner/repo-name",
  "jira_issue": "JIRA-1234",
  "package_name": "lodash",
  "current_version": "4.17.20",
  "fixed_version": "4.17.21",
  "vulnerability_id": "CVE-2021-23337",
  "severity": "HIGH",
  "description": "Optional description of the vulnerability"
}
```

### Required Fields
- `repository_name`: Full GitHub repository name (format: `owner/repo`)
- `jira_issue`: JIRA issue number (e.g., `JIRA-1234`)
- `package_name`: Name of the vulnerable package/library
- `current_version`: Current vulnerable version
- `fixed_version`: Target fixed version

### Optional Fields
- `vulnerability_id`: CVE or vulnerability identifier (default: `Unknown`)
- `severity`: Severity level - `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` (default: `MEDIUM`)
- `description`: Additional vulnerability description

## Environment Variables

### Required
- `GITHUB_TOKEN`: GitHub Personal Access Token with repo access

### Optional
- `ENVIRONMENT`: Deployment environment (default: `dev`)
- `LOGGER_LEVEL`: Logging level (default: `INFO`)
- `SENTRY_DSN`: Sentry DSN for error tracking
- `GITHUB_API_BASE_URL`: GitHub API URL (default: `https://api.github.com`)
- `COPILOT_USERNAME`: GitHub Copilot username (default: `copilot`)

## GitHub Issue Format

The Lambda creates issues with the following structure:

### Title
```
{JIRA-ISSUE}: Update {package} from {current_version} to {fixed_version}
```

### Body
- Severity indicator with emoji
- JIRA issue link
- Vulnerability ID
- Package information (current vs target version)
- Description
- Instructions for GitHub Copilot
- Branch naming requirements
- Commit message format
- Acceptance criteria checklist

### Labels
- `security`
- `dependency-update`
- `automated`

### Assignee
- GitHub Copilot (or configured username)

## Copilot PR Requirements

Issues instruct Copilot to:

1. **Branch Name**: `{jira-issue-lowercase}-update-{package-name}`
   - Example: `jira-1234-update-lodash`

2. **Commit Message**: `{JIRA-ISSUE}: Update {package} to {fixed_version}`
   - Example: `JIRA-1234: Update lodash to 4.17.21`

3. **Testing**: Ensure all tests pass

4. **Documentation**: Update docs if breaking changes introduced

## Development

### Prerequisites
- Docker
- Docker Compose
- uv (Python package manager)

### Local Development

1. **Build the Lambda function**:
   ```bash
   make build
   ```

2. **Run tests with linting**:
   ```bash
   make lint_and_test
   ```

3. **Run the function locally**:
   ```bash
   docker compose up function
   ```

4. **Test locally with a sample event**:
   ```bash
   curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" \
     -d '{
       "repository_name": "myorg/myrepo",
       "jira_issue": "SEC-123",
       "package_name": "requests",
       "current_version": "2.25.0",
       "fixed_version": "2.32.3",
       "vulnerability_id": "CVE-2024-1234",
       "severity": "HIGH",
       "description": "Critical security vulnerability in requests library"
     }'
   ```

### Project Structure

```
.
├── src/
│   ├── app.py                      # Lambda handler
│   └── github_issue_processor.py   # GitHub API logic
├── tests/
│   └── unit/                       # Unit tests
├── config.py                       # Configuration
├── pyproject.toml                  # Python dependencies
├── uv.lock                         # Locked dependencies
├── Dockerfile                      # Multi-stage Docker build
├── docker-compose.yaml             # Local development
├── Makefile                        # Build commands
├── lint-and-test.sh               # Test script
└── README.md                       # This file
```

## Testing

### Unit Tests
```bash
make lint_and_test
```

### Test Coverage
Generate HTML coverage report:
```bash
COV_REPORT=html make lint_and_test
```

The coverage report will be served at `http://localhost:8000`.

### Skip Linting
```bash
SKIP_LINT=1 make lint_and_test
```

## Deployment

This Lambda is designed to be deployed via Terraform or AWS SAM.

### IAM Permissions Required
- None (uses GitHub token for API access)

### Lambda Configuration
- **Runtime**: Python 3.13
- **Architecture**: x86_64 (linux/amd64)
- **Handler**: `src.app.handler` (wrapped by Datadog)
- **Timeout**: 30 seconds recommended
- **Memory**: 256 MB recommended

## Error Handling

The Lambda implements comprehensive error handling:

1. **Validation Errors**: Missing required fields in event payload
2. **GitHub API Errors**: HTTP errors when creating issues
3. **Network Errors**: Connection failures to GitHub
4. **Unexpected Errors**: All exceptions are logged and re-raised

All errors are logged via structured logging and optionally tracked in Sentry.

## Monitoring

### Datadog Integration
- Distributed tracing enabled via Datadog Lambda extension
- Custom metrics for issue creation success/failure
- Log forwarding to Datadog

### Sentry Integration
- Error tracking and alerting
- Request context and stack traces
- Performance monitoring

## References

Based on Lambda structure patterns from:
- `lambda-abacus/payoneer_payments_payout`
- `lambda-vector/job_priority_rule_match`
- `python-rds-utils/lambda/extract_native_configuration`

## License

Internal use only.