|
| 1 | +# API and Data Reference |
| 2 | + |
| 3 | +`@socketsecurity/scan-patterns` publishes five scanner tables through the root API and as raw JSON. Consumers can load and validate a table at runtime or import a specific JSON file at build time. The package export map is in [`package.json`](../package.json). |
| 4 | + |
| 5 | +## Scanner tables |
| 6 | + |
| 7 | +| Scanner | JSON file | Rules | Primary use | |
| 8 | +| -------------- | ------------------------------------------------------- | ----: | ------------------------------------------------------------------ | |
| 9 | +| `agentConfigs` | [`data/agent-configs.json`](../data/agent-configs.json) | 235 | Agent configuration files. | |
| 10 | +| `manifests` | [`data/manifests.json`](../data/manifests.json) | 4 | Secret rules scoped to package manifests and configuration paths. | |
| 11 | +| `secrets` | [`data/secrets.json`](../data/secrets.json) | 317 | Secret-detection patterns derived from the table's pinned sources. | |
| 12 | +| `skills` | [`data/skills.json`](../data/skills.json) | 418 | Agent-skill scanning patterns. | |
| 13 | +| `workflows` | [`data/workflows.json`](../data/workflows.json) | 41 | GitHub Actions workflow audits. | |
| 14 | + |
| 15 | +Rule counts are recorded from the checked-in tables. Each table includes `scanner`, `schemaVersion`, `sources`, and `rules`. Table shape changes require a schema-version change; source/rule updates do not by themselves change the schema version. |
| 16 | + |
| 17 | +## Runtime accessors |
| 18 | + |
| 19 | +The root module exports `getAgentConfigsTable()`, `getManifestsTable()`, `getSecretsTable()`, `getSkillsTable()`, and `getWorkflowsTable()`. `getPatternTable(scanner)` accepts a `ScannerName` and memoizes the parsed table after the first load. `loadPatternTable(scanner)` loads a table by scanner name and validates its shape. |
| 20 | + |
| 21 | +```ts |
| 22 | +import { findRuleById, getSecretsTable } from '@socketsecurity/scan-patterns' |
| 23 | + |
| 24 | +const rule = findRuleById(getSecretsTable(), 'trivy:aws-access-key-id') |
| 25 | +``` |
| 26 | + |
| 27 | +The root also exports `isPatternTable(value)`, `TABLE_FILE_BY_SCANNER`, `PATTERN_SEVERITY_ORDER`, and `PATTERN_TABLE_SCHEMA_VERSION`. Their exact signatures are in [`src/index.mts`](../src/index.mts) and [`src/load-table.mts`](../src/load-table.mts). |
| 28 | + |
| 29 | +## Rule schema |
| 30 | + |
| 31 | +`PatternTable` is the common container type. Each `PatternRule` records its id, title, description, category, severity, kind, engine dialect, regex flags, keyword prefilters, provenance, and optional regex/path-regex source and entropy threshold. |
| 32 | + |
| 33 | +| Field | Meaning | |
| 34 | +| ---------------------------------- | --------------------------------------------------------------------------- | |
| 35 | +| `id` | Stable rule identifier, unique within the table. | |
| 36 | +| `title`, `description`, `category` | Human-readable rule metadata. | |
| 37 | +| `severity` | `critical`, `high`, `medium`, `low`, or `info`. | |
| 38 | +| `kind` | `secret`, `audit`, `capability`, or `path`. | |
| 39 | +| `dialect` | `js` or `re2`, identifying the regex engine contract. | |
| 40 | +| `regexSource`, `regexFlags` | Content pattern and flags. A rule can omit a content pattern. | |
| 41 | +| `pathRegexSource` | Optional path-matching regex for path-scoped rules. | |
| 42 | +| `keywords` | Literal substrings that must occur before the regex is tried. | |
| 43 | +| `entropy` | Optional Shannon-entropy floor. | |
| 44 | +| `provenance` | Upstream license, rule identifier, pinned source tag, and source-file path. | |
| 45 | + |
| 46 | +See [`src/types.mts`](../src/types.mts) for `PatternRule`, `PatternTable`, `PatternProvenance`, `PatternKind`, `PatternDialect`, `PatternSeverity`, and `ScannerName` definitions. |
| 47 | + |
| 48 | +## Pattern compilation and matching |
| 49 | + |
| 50 | +`compileRuleRegex(rule)` creates a JavaScript `RegExp` only when the rule has a content pattern and `dialect: 'js'`. It returns `undefined` for `re2` rules and for rules without content patterns. `compileRulePathRegex(rule)` compiles a path expression only when the rule uses the JavaScript dialect and provides `pathRegexSource`. |
| 51 | + |
| 52 | +Consumers must route `re2` rules to an RE2-compatible engine. Treating `undefined` from `compileRuleRegex` as “there is no rule” would omit RE2 rules and non-content audit/capability rows. See [`src/load-table.mts`](../src/load-table.mts) for loader validation and compilation behavior. |
| 53 | + |
| 54 | +## Direct JSON imports |
| 55 | + |
| 56 | +Each published table is available through a data subpath. Import only the file a consumer needs: |
| 57 | + |
| 58 | +```js |
| 59 | +import secretsTable from '@socketsecurity/scan-patterns/data/secrets.json' with { type: 'json' } |
| 60 | + |
| 61 | +for (const rule of secretsTable.rules) { |
| 62 | + console.log(rule.id, rule.provenance.source) |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +Raw JSON imports support consumers that inline data during build. The runtime accessor API uses package files and memoizes loaded tables. Both forms use the same `PatternTable` data shape. |
| 67 | + |
| 68 | +## Provenance and support boundaries |
| 69 | + |
| 70 | +The `sources` field lists pinned upstream source tags for a table. Every rule has `provenance` with the upstream source, license, upstream rule id, and source file. See [`NOTICE`](../NOTICE) for attribution and license records. |
| 71 | + |
| 72 | +This package publishes detector patterns and contracts. It does not decide whether a build-tool invocation is trusted and does not provide license detection. The root README records these boundaries and the sources from which each scanner family is derived. |
0 commit comments