first commit

docs/security-stack/security/security-codes/src/patterns/ssh.md

@@ -0,0 +1,66 @@
+# ssh
+
+## Purpose
+
+Detects SSH private keys and public keys embedded in arbitrary strings.
+SSH private keys grant direct shell access to any server that has the
+corresponding public key in its `authorized_keys`. Public keys in authorized
+format can reveal the owner's cryptographic identity and are also worth
+flagging in security audits.
+
+## Features
+
+- Detects OpenSSH private key blocks (`-----BEGIN OPENSSH PRIVATE KEY-----`),
+  RSA public keys (`ssh-rsa AAAA…`), ECDSA keys (`ecdsa-sha2-nistp256 AAAA…`),
+  and Ed25519 keys (`ssh-ed25519 AAAA…`).
+- Private key blocks receive a higher confidence score (`0.98`) than public
+  keys (`0.92`).
+- All four regex patterns reset `lastIndex` before each scan.
+
+## Usage: Basic Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/ssh';
+
+const key = '-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXkAAAA=\n-----END OPENSSH PRIVATE KEY-----';
+const matches = detect(key);
+// matches[0].type === 'ssh-key', confidence 0.98
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detect } from '@suaveplan/security-codes/patterns/ssh';
+
+const config = 'authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ user@host';
+const matches = detect(config);
+// matches[0].type === 'ssh-key', confidence 0.92
+```
+
+## API Reference
+
+### `detect(input: string): SecurityCodeMatch[]`
+
+Scans `input` for SSH keys.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `string` | The string to scan (may contain newlines) |
+
+Returns `SecurityCodeMatch[]` with `type: 'ssh-key'`. Private key blocks
+have `confidence: 0.98`; public key formats have `confidence: 0.92`.
+
+## Implementation Notes
+
+OpenSSH private keys use PEM-like delimiters but with a specific header string
+that distinguishes them from generic PEM blocks detected by the `pem` module.
+Both modules may return matches for the same region — the detector deduplication
+layer resolves overlaps by preferring higher-confidence matches.
+
+Public key formats (`ssh-rsa`, `ecdsa-sha2-nistp256`, `ssh-ed25519`) are
+matched with a permissive `\S+` suffix to handle the variable-length base64
+blob and the optional trailing comment (e.g. `user@host`). The lower confidence
+score of `0.92` for public keys reflects the fact that a standalone `ssh-rsa
+AAAA…` string in a configuration file is common and not necessarily a secret
+leak, whereas an OpenSSH private key block is always sensitive and receives
+`0.98`.