Code Leaks Before You Push: Local PR Security with AWS SAM , Cedar and LocalStack
Catch exposed credentials while your commits are still local. This walkthrough explores how to construct a fast, self-contained terminal guardrail that evaluates Git diffs, sanitizes sensitive data, and logs immutable audit trails to a local S3 bucket.
Security feedback is most useful when it reaches developers before code leaves their machines.
A leaked API key, password, or environment file can be fixed quickly when detected locally. Once the same mistake reaches a remote repository, pull request, or CI pipeline, the cost of correcting it increases.
That idea led to PR Gatekeeper, a local security scanner for Git changes. The project reads a branch-aware Git diff, detects potential secrets and sensitive files, evaluates the findings with a Cedar policy, stores an audit record in a local S3-compatible environment, and generates an AI-assisted explanation of the result.
The goal is simple: give developers a fast security feedback loop without requiring them to push code first.
The Problem: Security Checks Often Arrive Too Late
It is surprisingly easy to commit sensitive information accidentally.
A developer might temporarily place a credential in a configuration file, create an environment file while testing, or leave a secret inside a change before committing it.
Many security systems detect these problems after the code has already been pushed. PR Gatekeeper moves the first layer of protection into the local development workflow.
The workflow is:
- Run
gatekeeperfrom the repository being checked.
- Determine the relevant Git diff for the current branch.
- Scan the diff for potential secrets and sensitive files.
- Redact detected secret values.
- Evaluate the findings using Cedar.
- Store the evaluation as a local audit record.
- Ask an AI agent to explain the sanitized findings.
The final result is an
ALLOW or DENY decision accompanied by information that a developer can use to fix the problem.Setting Up the Local Developer Workflow
PR Gatekeeper uses LocalStack to provide a local S3-compatible environment for audit records.
Start the LocalStack container from your development machine:
docker run --rm -it -p 4566:4566 localstack/localstack
The project also uses AWS SAM to build the Lambda-compatible application environment.
Before building, configure the required AI API credential in your local environment:
$env:GEMINI_API_KEY = 'your-key-here'
Then build the project using the containerized SAM environment:
sam build --use-container
Using the containerized build helps keep the development environment closer to the Lambda runtime.
Making the Scanner Available from Any Repository
Instead of requiring developers to navigate to the PR Gatekeeper directory every time, I added a PowerShell function to my PowerShell profile.
The function points to the scanner's location:
function gatekeeper { & python "C:\path\to\pr-gatekeeper\master_script\scan_pr.py"}
After opening a new PowerShell session, the scanner can be invoked with:
gatekeeper
The important part is that the scanner uses the current working directory as the repository being inspected.
This means PR Gatekeeper only needs to be installed once. I can move into another Git repository and run the same command without copying scripts or modifying that repository.
Reading the Correct Git Diff
One of the more important parts of the project was determining which changes should actually be scanned.
The scanner uses a branch-aware strategy rather than simply checking uncommitted files.
When running on
main or master , it compares the latest commit with its predecessor.On a feature branch, it attempts to locate an appropriate base branch and determines the merge base before comparing the changes with the current
HEAD .If an appropriate base reference cannot be found, the scanner falls back to the previous commit.
This produces a local representation of the changes that would normally be reviewed as part of a pull request.
The resulting diff is then packaged together with repository metadata and passed into the security workflow.
Challenge 1: Running the Scanner from Any Repository
The first challenge was avoiding a scanner that only worked inside its own project directory.
The useful version needed to do two separate things:
- Locate the PR Gatekeeper application.
- Inspect whichever repository the developer was currently working in.
The PowerShell function handles the first responsibility by pointing to the scanner installation.
The Python application handles the second by treating the current working directory as the repository being inspected.
This separation made the developer experience much simpler:
Repository A ↓gatekeeper ↓PR Gatekeeper ↓Git diff from Repository A
The same command can then be used from Repository B, Repository C, or any other local Git repository.
Scan Locally and Redact Before Using AI
The scanner examines the original diff locally before creating the sanitized version that is passed to the AI component.
The initial rules intentionally focus on a small set of understandable patterns.
Finding | What it detects |
|---|---|
AWS_KEY | AWS access-key or secret-key assignments |
GENERIC_SECRET | API keys, secrets, passwords, or bearer tokens |
COMMITTED_ENV_FILE | A changed environment file |
For example, a detected value is replaced before the diff is sent to the AI component:
- api_key = "value-that-should-not-be-committed"+ api_key = "<REDACTED_SECRET>"
The scanner retains information about the type and number of findings while removing the sensitive value itself.
This gives the policy engine enough information to make a decision without requiring the original secret to be included in the AI prompt.
Regex Scanning Is Not a Complete Secret-Management System
The scanner deliberately remains simple.
Regular expressions can miss unusual secret formats and can also generate false positives. Therefore, PR Gatekeeper is not intended to replace proper secret management, repository protection, or CI security scanning.
Instead, it provides an additional local layer that catches common mistakes before they leave the developer's machine.
Using Cedar for the Security Decision
The project uses Cedar to make the authorization decision.
The application provides Cedar with information such as:
- Whether a potential secret was detected.
- How many vulnerabilities were found.
The policy denies the operation when a secret is detected or when vulnerabilities are present.
A simplified version of the policy looks like this:
forbid ( principal, action == Action::"merge_pull_request", resource)when { context.has_leaked_secret == true || context.vulnerability_count > 0};
A corresponding permit rule allows the expected developer action when the request satisfies the required conditions.
The application maps the Cedar result to either
ALLOW or DENY .An important design decision is that the application fails closed. If the Cedar policy cannot be loaded or evaluated, the change is treated as denied rather than silently allowing it.
This gives the system a clear separation of responsibilities:
Cedar makes the security decision.
AI explains the decision.
The AI model does not have authority to override the security policy.
Creating a Local Audit Record
Each evaluation attempts to create an audit record in an S3-compatible bucket provided by LocalStack.
The record contains information such as:
- Timestamp
- Decision
- Secret detection status
- Vulnerability count
- Finding types
- Repository metadata
A simplified audit record looks like this:
{ "timestamp": "2026-09-19T16:01:19.123456+00:00", "decision": "DENY", "has_leaked_secret": true, "vulnerability_count": 1, "detected_issues": [ "GENERIC_SECRET" ]}
Because the S3 service is running locally, the project can demonstrate the audit workflow without creating actual cloud resources.
The audit objects can also be inspected through the AWS CLI by targeting the local S3-compatible service.
Using AI for Explanation, Not Authorization
After the deterministic security checks have completed, PR Gatekeeper sends the sanitized diff and scanner findings to a Strands Agent configured with Gemini.
The agent produces a structured explanation containing sections such as:
## Vulnerabilities
## How to Potentially Fix
## Summary of PR
The prompt explicitly treats the diff as untrusted input.
This is important because source code can contain text that looks like instructions. The AI should analyze the scanner's findings rather than treating arbitrary source-code content as instructions.
The AI is also instructed not to invent vulnerabilities that were not identified by the security scanner.
This creates another important separation:
Git Diff ↓Local Security Scanner ↓Cedar Policy ↓ALLOW / DENY ↓Sanitized Findings ↓AI Explanation
The deterministic security layer controls the gate, while the AI layer makes the result easier for developers to understand.
Building the Project with AWS SAM
The project uses AWS SAM to package the application as a Python Lambda function.
The SAM template defines the main function with the required runtime, memory, and timeout configuration.
A simplified resource definition looks like this:
Resources: PRGatekeeperFunction: Type: AWS::Serverless::Function Properties: CodeUri: . Handler: app.lambda_handler
The project is built using:
sam build --use-container
The containerized build provides an environment closer to the Lambda runtime and helps identify dependency issues before deployment.
The local architecture can later be adapted to a deployed environment without fundamentally changing the scanning workflow.
Challenge 2: Preparing the Container Environment
Another challenge was getting the local container environment working correctly.
SAM requires Docker when using the containerized build process. On the first build, Docker may also need to download the appropriate Lambda-compatible build image.
That initial setup takes some time, but it provides a more consistent environment for packaging the application.
LocalStack is another part of the local container setup. It provides the S3-compatible service used for audit records.
Together, the two tools create a realistic local development environment:
Developer Machine│├── Docker│ ├── AWS SAM build environment│ └── LocalStack│└── PR Gatekeeper ├── Git diff ├── Secret scanner ├── Cedar policy ├── Audit logging └── AI explanation
One networking detail is particularly important when containers communicate with services running outside their own container.
From the host machine, the LocalStack service can be accessed through the local machine address.
When the Lambda handler is running inside a container, however,
localhost refers to that container itself. The container therefore needs to use the appropriate host gateway address to reach a service running on the host.This distinction is easy to miss when developing locally.
What This Project Demonstrates
PR Gatekeeper demonstrates that useful security tooling does not necessarily require a large infrastructure stack.
A local Git diff, a focused secret scanner, a deterministic Cedar policy, a local S3-compatible audit store, and an AI explanation layer can be combined into a practical developer workflow.
The interesting part of the project was not any individual service. It was connecting the pieces into one workflow that a developer can actually use.
The most important architectural lesson for me was the separation between decision-making and explanation.
Security decisions should remain deterministic and inspectable.
Generative AI can then be used to explain those decisions, summarize findings, and provide developers with actionable remediation guidance.
That gives developers fast local feedback while avoiding a design where a language model has authority over the security gate itself.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article