Initial Commit

packages/security-stack/security/security-codes/src/patterns/aws.md

@@ -0,0 +1,59 @@
+# aws
+
+## Purpose
+
+Detects AWS Access Key IDs within arbitrary string input. AWS Access Key IDs
+are 20-character alphanumeric identifiers that always begin with the prefix
+`AKIA`. Detecting these in log lines, source code, or configuration strings
+prevents inadvertent credential exposure.
+
+## Features
+
+- Regex-based detection using the canonical `AKIA[0-9A-Z]{16}` pattern.
+- Word-boundary anchors (`\b`) reduce false positives from longer strings.
+- Returns a confidence score of `0.95` — the fixed prefix makes false
+  positives very unlikely.
+- Resets `lastIndex` before each scan so the exported function is safe for
+  repeated calls on different inputs.
+
+## Usage: Basic Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/aws';
+
+const matches = detect('Key: AKIAIOSFODNN7EXAMPLE');
+// matches[0].type === 'aws-access-key'
+// matches[0].confidence === 0.95
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/aws';
+
+const log = 'aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret=abc123';
+const matches = detect(log);
+console.log(matches[0].start, matches[0].end);
+// 20, 40  (covers just the key ID)
+```
+
+## API Reference
+
+### `detect(input: string): SecurityCodeMatch[]`
+
+Scans `input` for AWS Access Key IDs.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `string` | The string to scan |
+
+Returns an array of `SecurityCodeMatch` objects. Each match records the
+matched value, its `[start, end)` position, and a `confidence` of `0.95`.
+Returns an empty array when no keys are found.
+
+## Implementation Notes
+
+The pattern `/\bAKIA[0-9A-Z]{16}\b/g` is the standard detection heuristic
+recommended by AWS and used by tools such as truffleHog and git-secrets.
+Secret Access Keys (the companion credential) are not detected here because
+they have no fixed prefix and are better covered by the entropy detector.