@bouncesecurity/aghast 0.0.13

package/README.md

@@ -0,0 +1,111 @@
+# AI Guided Hybrid Application Static Testing (AGHAST) - ALPHA VERSION
+
+![Status: Alpha](https://img.shields.io/badge/Status-Alpha-orange)
+[![CI](https://github.com/BounceSecurity/aghast/actions/workflows/ci.yml/badge.svg)](https://github.com/BounceSecurity/aghast/actions/workflows/ci.yml)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![By Bounce Security](https://img.shields.io/badge/By-Bounce_Security-f79421)](https://bouncesecurity.com/)
+
+> **Warning**
+> AGHAST is in **early alpha**. APIs, CLI flags, configuration formats, and output schemas may change between releases without notice. Use in production CI/CD pipelines at your own risk.
+
+An open source tool that combines static scanning rules with AI prompts to find code-specific and company-specific security issues.
+
+Define static rules, security checks as markdown instructions, point AGHAST at a repo, and get structured results (JSON or SARIF).
+
+<p align="center">
+  <img src="/assets/img/aghastbouncecaption.png" alt="AGHAST" width="50%">
+</p>
+
+## What AGHAST Does
+
+You can read the full background to this tool in our blogpost [here](https://bouncesecurity.com/aghast) but, to cut to the chase, AGHAST helps you run three types of checks:
+
+- Pure AI scanning rules - let the LLM do all the analysis
+- A combination of a static rule and an AI scanning rule - the sweet spot for most use cases
+- Purely static rules - for completeness, when a traditional static rule is all you need
+
+The beauty of the approach is what you *don't* need:
+
+- You don't need to modify the code
+- You don't need to build something into the codebase
+- You don't need to write code in the language of the codebase
+
+All you need is:
+
+- Access to the codebase
+- An understanding of the problem you are trying to discover
+- The ability to write some simple rules
+
+There are almost certainly other ways of achieving this, but to our mind, this approach is both straightforward and deterministic.
+
+## Prerequisites
+
+- **Node.js 20+**
+- **[Semgrep Community Edition](https://semgrep.dev/docs/getting-started/)** (LGPL-2.1, optional) — only needed for checks that use Semgrep rules
+- **Anthropic API key** — for AI-based checks (not needed for semgrep-only checks)
+
+## Installation
+
+See the [Getting Started Guide](docs/getting-started.md) for full installation and setup instructions.
+
+## Quick Start
+
+Set your API key, create a check, and run a scan:
+
+```bash
+export ANTHROPIC_API_KEY=your-api-key
+aghast new-check --config-dir ./my-checks
+aghast scan /path/to/target-repo --config-dir ./my-checks
+```
+
+See the [Getting Started Guide](docs/getting-started.md) for a full walkthrough.
+
+## Example Output
+
+Results are structured JSON (or SARIF) with per-check status and detailed issues:
+
+```json
+{
+  "checks": [
+    { "checkId": "aghast-api-authz", "checkName": "API Authorization Check", "status": "FAIL", "issuesFound": 1 },
+    { "checkId": "aghast-sql-injection", "checkName": "SQL Injection Prevention", "status": "PASS", "issuesFound": 0 }
+  ],
+  "issues": [
+    {
+      "checkId": "aghast-api-authz",
+      "checkName": "API Authorization Check",
+      "file": "src/api/users.ts",
+      "startLine": 45,
+      "endLine": 52,
+      "description": "Missing authorization check on DELETE endpoint.",
+      "codeSnippet": "router.delete('/users/:id', async (req, res) => {"
+    }
+  ],
+  "summary": {
+    "totalChecks": 2,
+    "passedChecks": 1,
+    "failedChecks": 1,
+    "flaggedChecks": 0,
+    "errorChecks": 0,
+    "totalIssues": 1
+  }
+}
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — installation, setup, and first scan
+- [Scanning](docs/scanning.md) — scan command options, environment variables, output formats
+- [Creating Checks](docs/creating-checks.md) — scaffolding new security checks
+- [Configuration Reference](docs/configuration.md) — check schemas, check types, runtime config
+- [Development](docs/development.md) — setup, building, testing, releasing
+
+## Contributing
+
+We welcome bug reports and feature requests via [GitHub Issues](https://github.com/BounceSecurity/aghast/issues). We are not currently accepting pull requests.
+
+## License
+
+This project is licensed under the [GNU Affero General Public License v3.0 or later](LICENSE).
+
+Copyright (C) 2026 [Bounce Consulting Ltd.](https://bouncesecurity.com/)

package/config/prompts/generic-instructions.md

@@ -0,0 +1,56 @@
+GENERIC INSTRUCTIONS:
+
+You are performing a SPECIFIC security check as defined in the CHECK INSTRUCTIONS below.
+
+IMPORTANT:
+- Focus ONLY on what the CHECK INSTRUCTIONS ask you to validate
+- Do NOT perform general security testing or look for unrelated vulnerabilities
+- Do NOT report issues outside the scope of the specific check
+- Follow the CHECK INSTRUCTIONS exactly as written
+
+OUTPUT FORMAT:
+
+Return your findings in the following JSON format:
+
+{
+  "issues": [
+    {
+      "file": "relative/path/to/file.ts",
+      "startLine": 40,
+      "endLine": 45,
+      "description": "Detailed explanation (see requirements below)",
+      "dataFlow": [
+        { "file": "src/routes/handler.ts", "lineNumber": 12, "label": "User input received from request parameter" },
+        { "file": "src/services/query.ts", "lineNumber": 38, "label": "Input passed to SQL query without sanitization" }
+      ]
+    }
+  ]
+}
+
+DESCRIPTION FORMATTING REQUIREMENTS:
+
+Your description field MUST be detailed and well-structured:
+- Use markdown formatting with headings (## Heading), bullet points, code blocks
+- Use \n for line breaks to create structured, readable content
+- Include an "Attack Scenario" section demonstrating exploitation
+- Include a "Recommendation" section with specific remediation steps
+
+DATA FLOW REQUIREMENTS:
+
+When the issue involves data flowing through multiple locations (e.g., user input reaching a dangerous sink), include a "dataFlow" array. Each step represents a point in the call stack or data flow:
+- "file": relative path to the source file
+- "lineNumber": the line number at that step
+- "label": a short description of what happens at this point (e.g., "User input received", "Passed to database query")
+- Order steps from source (e.g., user input) to sink (e.g., SQL execution)
+- Omit "dataFlow" entirely if the issue is localized to a single location
+
+CRITICAL: Return ONLY valid JSON. No markdown code blocks, no explanations outside the JSON.
+
+If no issues found for this SPECIFIC check, return: {"issues": []}
+
+If a TARGET LOCATION section appears at the end of this prompt, you must analyze ONLY that specific code location.
+
+---
+
+CHECK INSTRUCTIONS:
+

package/config/prompts/test-cheaper-instructions.md

@@ -0,0 +1,57 @@
+GENERIC INSTRUCTIONS:
+
+You are performing a SPECIFIC security check as defined in the CHECK INSTRUCTIONS below.
+
+IMPORTANT:
+- Focus ONLY on what the CHECK INSTRUCTIONS ask you to validate
+- Make sure you read the CHECK INSTRUCTIONS in full and comply with them
+- Do NOT perform general security testing or look for unrelated vulnerabilities
+- Do NOT report issues outside the scope of the specific check
+- Follow the CHECK INSTRUCTIONS exactly as written
+
+OUTPUT FORMAT:
+
+Return your findings in the following JSON format:
+
+{
+  "issues": [
+    {
+      "file": "relative/path/to/file.ts",
+      "startLine": 40,
+      "endLine": 45,
+      "description": "Detailed explanation (see requirements below)",
+      "dataFlow": [
+        { "file": "src/routes/handler.ts", "lineNumber": 12, "label": "User input received from request parameter" },
+        { "file": "src/services/query.ts", "lineNumber": 38, "label": "Input passed to SQL query without sanitization" }
+      ]
+    }
+  ]
+}
+
+DESCRIPTION FORMATTING REQUIREMENTS:
+
+Your description field MUST be detailed and well-structured:
+- Use markdown formatting with headings (## Heading), bullet points
+- Use \n for line breaks to create structured, readable content
+- No need for "Example Attack" or a "Details" sections
+- Keep description as short as possible.
+
+DATA FLOW REQUIREMENTS:
+
+When the issue involves data flowing through multiple locations (e.g., user input reaching a dangerous sink), include a "dataFlow" array. Each step represents a point in the call stack or data flow:
+- "file": relative path to the source file
+- "lineNumber": the line number at that step
+- "label": a short description of what happens at this point (e.g., "User input received", "Passed to database query")
+- Order steps from source (e.g., user input) to sink (e.g., SQL execution)
+- Omit "dataFlow" entirely if the issue is localized to a single location
+
+CRITICAL: Return ONLY valid JSON. No markdown code blocks, no explanations outside the JSON.
+
+If no issues found for this SPECIFIC check, return: {"issues": []}
+
+If a TARGET LOCATION section appears at the end of this prompt, you must analyze ONLY that specific code location.
+
+---
+
+CHECK INSTRUCTIONS:
+

package/dist/check-library.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Check Library / Config Manager.
+ * Two-layer config: Layer 1 (registry) maps checks to repos,
+ * Layer 2 (<id>.json) defines each check in its own folder.
+ * Implements spec Appendix B.1.
+ */
+import type { SecurityCheck, CheckDetails, CheckRegistryEntry, CheckDefinition } from './types.js';
+export interface CheckRegistry {
+    checks: CheckRegistryEntry[];
+}
+/**
+ * Load and parse the Layer 1 registry from <configDir>/checks-config.json.
+ * Throws on missing file, malformed JSON, or invalid structure.
+ */
+export declare function loadCheckRegistry(configDir: string): Promise<CheckRegistry>;
+/**
+ * Load and parse a Layer 2 check definition from <checkFolderPath>/<id>.json.
+ * Throws on missing file, malformed JSON, or missing required fields.
+ */
+export declare function loadCheckDefinition(checkFolderPath: string): Promise<CheckDefinition>;
+/**
+ * Scan check directories for subfolders containing <id>.json.
+ * Returns a map of check id → folder path.
+ */
+export declare function discoverCheckFolders(checksDirs: string[]): Promise<Map<string, string>>;
+/**
+ * Merge Layer 1 registry entries with Layer 2 check definitions.
+ * Resolves instructionsFile and checkTarget.rules paths relative to check folder.
+ * Throws if a registry entry has no matching check folder.
+ */
+export declare function resolveChecks(registry: CheckRegistry, checkFolders: Map<string, string>): Promise<SecurityCheck[]>;
+export interface CheckLibraryConfig {
+    checks: SecurityCheck[];
+}
+/**
+ * Load and parse a flat JSON config file (old format).
+ * Kept for backward compatibility with existing test fixtures.
+ */
+export declare function loadConfig(configPath: string): Promise<CheckLibraryConfig>;
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate a single SecurityCheck definition.
+ * Checks that id is present and non-empty, and instructionsFile exists on disk.
+ * basePath is used to resolve instructionsFile if it's a relative path.
+ * If instructionsFile is already absolute, basePath is ignored.
+ */
+export declare function validateCheck(check: SecurityCheck, basePath: string): Promise<ValidationResult>;
+export { normalizeRepoPath } from './repository-analyzer.js';
+/**
+ * Check if a single check matches the given repository URL/path.
+ * Empty repositories array matches all repos.
+ * Uses bidirectional substring matching on normalized paths.
+ */
+export declare function checkMatchesRepository(check: SecurityCheck, repositoryUrl: string): boolean;
+/**
+ * Filter checks to those matching the given repository URL/path.
+ * Also filters out disabled checks (enabled === false).
+ */
+export declare function filterChecksForRepository(checks: SecurityCheck[], repositoryUrl: string): SecurityCheck[];
+/**
+ * Parse a markdown check file into CheckDetails.
+ * Extracts name from first ### heading, overview from #### Overview section.
+ */
+export declare function parseCheckMarkdown(id: string, markdown: string): CheckDetails;
+/**
+ * Load check instructions from the markdown file referenced by a SecurityCheck.
+ * Resolves instructionsFile relative to basePath (or uses absolute path if already resolved).
+ */
+export declare function loadCheckDetails(check: SecurityCheck, basePath: string): Promise<CheckDetails>;
+/**
+ * Filter files to those matching applicablePaths globs.
+ * If applicablePaths is undefined or empty, returns all files.
+ */
+export declare function filterApplicablePaths(files: string[], applicablePaths?: string[]): string[];
+/**
+ * Filter out files matching excludedPaths globs.
+ * If excludedPaths is undefined or empty, returns all files.
+ */
+export declare function filterExcludedPaths(files: string[], excludedPaths?: string[]): string[];
+/**
+ * Apply both applicablePaths and excludedPaths filtering.
+ */
+export declare function filterCheckPaths(files: string[], check: SecurityCheck): string[];
+//# sourceMappingURL=check-library.d.ts.map

package/dist/check-library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-library.d.ts","sourceRoot":"","sources":["../src/check-library.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,eAAe,EAChB,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA0DjF;AAID;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA8E3F;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA2B9B;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,aAAa,EACvB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC,aAAa,EAAE,CAAC,CAmD1B;AAID,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiChF;AAID,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CAyB3B;AAKD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAcT;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,aAAa,EAAE,EACvB,aAAa,EAAE,MAAM,GACpB,aAAa,EAAE,CAIjB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAoB7E;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAgBvB;AAOD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EAAE,EACf,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,MAAM,EAAE,CAOV;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB,MAAM,EAAE,CAOV;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,aAAa,GACnB,MAAM,EAAE,CAGV"}