Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/workflows/security-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: GuardDog checks
on:
pull_request:
push:
branches: [develop]
permissions:
contents: read
packages: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
cache: npm
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: npm run build
- run: npm run test:ci -- --runInBand
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ npm install # needs NODE_AUTH_TOKEN for @jonverrier/prompt-reposito
npm run build # rimraf dist && tsc && copy Prompts.json
npm run test:ci # unit tests; no OPENAI_API_KEY
npm pack --dry-run # verify dist-only tarball
npm run review:strongai-platforms -- --dry-run # needs CURSOR_API_KEY + OPENAI_API_KEY
npm run review:strongai-platforms -- --dry-run # plan only; does not launch cloud agents
```

**StrongAI cloud reviews:** `guarddog review-strongai-platforms` launches one Cursor cloud agent per platform package, writes StrongAI `issues/*.md` drafts, and can invoke `tools/build/scripts/sync-issues-to-github.sh` with `--sync --confirm`. See README § StrongAI platform cloud reviews.
Expand Down
10 changes: 7 additions & 3 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,11 +178,15 @@ These rules must not break during evolution:

5. **Sampled reviews are visible.** Set `sampledReview: true` only when the **source** layer skips ranked files (`truncation.source`). C4 or design discards are reported in `contextCoverage` and `layerPack` without marking a sampled review. Always log and render whether ranking was **C4-guided** vs **heuristic** separately from discards.

6. **Read-only target scan.** Do not modify source files in the repository under review. Side effects are limited to configured outputs and optional GitHub issues.
6. **Read-only target scan.** Do not modify source files in the repository under review. Side effects are limited to report files inside the repository and GitHub issues requested on the CLI.

7. **Gitignore respected.** Repository walks honour `.gitignore` patterns via `utils/fileSystem.ts`.
7. **Repository path confinement.** Design files, context reads, and Markdown/JSON reports stay inside the repository root. Reject absolute paths, parent traversal, and symlinks. Redact private-key blocks and other obvious secrets before that text is sent to an LLM.

8. **No monorepo coupling.** GuardDog must remain installable and runnable without the StrongAI workspace. Peer relationship to AutoDoc is documented, not wired.
8. **Untrusted repo config cannot publish.** `github.enabled` and `github.repo` in the target config do not create issues or choose a repository. Cloud review forwards `NODE_AUTH_TOKEN` only when that variable is set, and `--dry-run` does not launch cloud agents.

9. **Gitignore respected.** Repository walks honour `.gitignore` patterns via `utils/fileSystem.ts`.

10. **No monorepo coupling.** GuardDog must remain installable and runnable without the StrongAI workspace. Peer relationship to AutoDoc is documented, not wired.

---

Expand Down
34 changes: 19 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,15 +314,15 @@ guarddog review <repoPath> \

| Option | Description |
|--------|-------------|
| `--design <path>` | Architecture intent / design file |
| `--out <path>` | Markdown output path |
| `--json <path>` | JSON output path |
| `--design <path>` | Architecture intent / design file inside the repository |
| `--out <path>` | Markdown output path inside the repository |
| `--json <path>` | JSON output path inside the repository |
| `--min-severity <level>` | `low` \| `medium` \| `high` \| `critical` (default: `medium`) |
| `--min-impact <level>` | `low` \| `medium` \| `high` \| `critical` (default: `medium`) |
| `--max-findings <number>` | Limit number of findings (default: 20) |
| `--dry-run` | Do not write files or create issues |
| `--github-issue` | Enable GitHub issue creation |
| `--repo <owner/name>` | GitHub repo target |
| `--github-issue` | Enable GitHub issue creation (not taken from the target repo config) |
| `--repo <owner/name>` | GitHub repo target (not taken from the target repo config) |
| `--issue-mode single\|per-finding` | Issue creation mode (default: `single`) |
| `--model <model-name>` | LLM model name |
| `--context-token-budget <n>` | Source file token budget (default: `32000`) |
Expand Down Expand Up @@ -362,7 +362,11 @@ guarddog review . \
--confirm
```

Requires `GITHUB_TOKEN`. Without `--confirm`, issue title and body are printed only (dry-run).
Requires `GITHUB_TOKEN` and both `--github-issue` and `--repo`. Without `--confirm`, issue title and body are printed only (dry-run).

`github.enabled` and `github.repo` in `.guarddog/guarddog.config.json` are ignored. A repository under review cannot turn issue creation on or choose the destination. `github.issueMode` from that file is still used unless `--issue-mode` is passed.

`--design`, `--out`, `--json`, and the same fields in the config file must stay inside the repository. Absolute paths, `..` segments, and symlinks are rejected. Design and source text is redacted for obvious secrets, including OpenSSH private keys, before it is sent to the model.

---

Expand All @@ -371,19 +375,19 @@ Requires `GITHUB_TOKEN`. Without `--confirm`, issue title and body are printed o
Launch **one Cursor cloud agent per platform package** (`platform`, `platform-client`, `platform-server`), run GuardDog against that package's `DESIGN.md`, then write **one StrongAI inbox issue per package** and optionally sync those files to real GitHub issues.

```bash
# 1) Dry-run: cloud reviews + local drafts under .guarddog/strongai-issue-drafts/
export CURSOR_API_KEY=cursor_...
export OPENAI_API_KEY=sk-...
# Optional: private npm auth for GuardDog deps inside the cloud VM
export NODE_AUTH_TOKEN=${GITHUB_TOKEN}

# 1) Dry-run: print the review plan. Does not launch agents or send tokens.
npm run build
npm run review:strongai-platforms -- --dry-run

# Or via the CLI directly:
node dist/cli/index.js review-strongai-platforms --dry-run

# 2) Write into the local StrongAI issues/ inbox (no GitHub yet)
# 2) Launch cloud agents and write into the local StrongAI issues/ inbox (no GitHub yet)
export CURSOR_API_KEY=cursor_...
export OPENAI_API_KEY=sk-...
# Optional npm auth inside the cloud VM. Set this explicitly; GITHUB_TOKEN is not forwarded.
export NODE_AUTH_TOKEN=...

node dist/cli/index.js review-strongai-platforms \
--strongai-path ../StrongAI

Expand Down Expand Up @@ -414,7 +418,7 @@ That script creates GitHub issues on `jonverrier/StrongAI` and writes `**GitHub:

| Option | Description |
|--------|-------------|
| `--dry-run` | Write drafts under `.guarddog/strongai-issue-drafts/` (skip StrongAI/issues and sync) |
| `--dry-run` | Print which packages would be reviewed. Does not launch cloud agents, send tokens, or write drafts |
| `--sync` | After writing `issues/`, run StrongAI `sync-issues-to-github.sh` |
| `--confirm` | With `--sync`, actually create GitHub issues (otherwise print the sync command only) |
| `--strongai-path <path>` | Local StrongAI monorepo root (default: `STRONGAI_PATH` or `../StrongAI`) |
Expand Down Expand Up @@ -509,7 +513,7 @@ When `truncation.budgetExhausted` is true, the review output notes a **sampled r
| `CURSOR_API_KEY` | Required for `review-strongai-platforms` cloud agents ([Dashboard → Integrations](https://cursor.com/dashboard/integrations)) |
| `STRONGAI_PATH` | Optional local StrongAI monorepo root for writing `issues/*.md` |
| `GITHUB_TOKEN` | Required for confirmed GitHub issue creation / StrongAI issue sync (`gh`) |
| `NODE_AUTH_TOKEN` | Optional; passed into cloud VMs for GitHub Packages (`@jonverrier/*`) installs |
| `NODE_AUTH_TOKEN` | Optional. When set, passed into cloud VMs for GitHub Packages (`@jonverrier/*`) installs. `GITHUB_TOKEN` is never copied into this variable |
| `GUARDDOG_DEBUG` | Set to `1` for debug logging |

---
Expand Down
27 changes: 19 additions & 8 deletions src/cli/commands/review.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ import { runReview } from '../../core/reviewer';
import { loadConfig } from '../../core/configLoader';
import { parseImpact, parseSeverity } from '../../core/configLoader';
import { createGitHubIssues } from '../../github/githubClient';
import { renderPerFindingIssues, renderSingleIssue } from '../../github/issueRenderer';
import { IIssueDraft, renderPerFindingIssues, renderSingleIssue } from '../../github/issueRenderer';
import { IReviewCliOptions, IssueMode } from '../../schemas/config';
import { IReviewResult } from '../../schemas/finding';
import { resolveRepoPath } from '../../utils/fileSystem';
import { defaultLogger } from '../../utils/logger';
import { InvalidParameterError } from '../../utils/errors';
Expand All @@ -31,18 +32,15 @@ export async function runReviewCommand(args: string[]): Promise<number> {
const reviewResult = await runReview({ ...options, repoPath }, defaultLogger);
const config = await loadConfig(repoPath, { ...options, repoPath });

if (config.github.enabled) {
const githubRequested = options.githubIssue === true && options.noGithub !== true;
if (githubRequested) {
const confirm = options.confirm === true;
const repo = config.github.repo;
const repo = options.repo;
if (!repo) {
throw new InvalidParameterError('--repo owner/name is required with --github-issue.');
}

const drafts =
config.github.issueMode === 'per-finding'
? renderPerFindingIssues(reviewResult.result)
: [renderSingleIssue(reviewResult.result)];

const drafts = issueDraftsForMode(config.github.issueMode, reviewResult.result);
await createGitHubIssues(repo, drafts, confirm, defaultLogger);
}

Expand All @@ -52,6 +50,19 @@ export async function runReviewCommand(args: string[]): Promise<number> {
return 0;
}

function issueDraftsForMode(issueMode: IssueMode, result: IReviewResult): IIssueDraft[] {
switch (issueMode) {
case 'per-finding':
return renderPerFindingIssues(result);
case 'single':
return [renderSingleIssue(result)];
default: {
const unexpected: never = issueMode;
throw new InvalidParameterError(`Invalid issue mode: ${String(unexpected)}`);
}
}
}

function parseReviewArgs(args: string[]): { repoPath: string; options: IReviewCliOptions } {
if (args.length === 0 || args[0].startsWith('--')) {
throw new InvalidParameterError('review requires a <repoPath> argument.');
Expand Down
36 changes: 24 additions & 12 deletions src/cli/commands/reviewStrongAiPlatforms.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,16 @@ export async function runReviewStrongAiPlatformsCommand(args: string[]): Promise
const strongAiRoot = resolveStrongAiRoot(options.strongAiPath, guardDogRoot);
const targets = resolveTargets(options.packages);

if (options.dryRun) {
defaultLogger.info(
`[dry-run] Would launch cloud agents for ${targets.map((t) => t.id).join(', ')} against StrongAI at ${strongAiRoot}.`
);
defaultLogger.info(
'[dry-run] Cloud agents are not started. No tokens are sent and no issue drafts are written.'
);
return 0;
}

const apiKey = process.env.CURSOR_API_KEY?.trim() ?? '';
const openAiApiKey = process.env.OPENAI_API_KEY?.trim() ?? '';
if (!apiKey) {
Expand All @@ -73,20 +83,17 @@ export async function runReviewStrongAiPlatformsCommand(args: string[]): Promise
guardDogRepoUrl: options.guardDogRepoUrl,
strongAiStartingRef: options.strongAiStartingRef,
guardDogStartingRef: options.guardDogStartingRef,
nodeAuthToken: process.env.NODE_AUTH_TOKEN?.trim() || process.env.GITHUB_TOKEN?.trim(),
nodeAuthToken: readNodeAuthToken(),
preferLocalIssueRender: options.preferLocalIssueRender
},
defaultLogger
);

const outputDir = resolveOutputDir(options, strongAiRoot, guardDogRoot);
const outputDir = resolveOutputDir(options, strongAiRoot);
const writeResult = await writeStrongAiIssueDrafts(
{
drafts,
outputDir,
// Always write draft files unless the caller asked for a pure command dry-run
// that only reports intent. Here dry-run means "do not sync to GitHub" and
// write under a GuardDog output folder instead of StrongAI/issues.
dryRun: false
},
defaultLogger
Expand All @@ -98,9 +105,9 @@ export async function runReviewStrongAiPlatformsCommand(args: string[]): Promise
}

if (options.sync) {
if (options.dryRun || outputDir !== resolveStrongAiIssuesDir(strongAiRoot)) {
if (outputDir !== resolveStrongAiIssuesDir(strongAiRoot)) {
defaultLogger.info(
'Skipping GitHub sync because dry-run output is not StrongAI/issues. Re-run without --dry-run and with --sync --confirm.'
'Skipping GitHub sync because output is not StrongAI/issues. Re-run without --out-dir and with --sync --confirm.'
);
} else {
await syncStrongAiIssuesToGitHub(
Expand All @@ -120,17 +127,22 @@ export async function runReviewStrongAiPlatformsCommand(args: string[]): Promise
return 0;
}

/**
* Package-install token for the cloud VM.
* `GITHUB_TOKEN` is not copied: it is a publish credential, not an npm token for a remote agent.
*/
function readNodeAuthToken(): string | undefined {
const token = process.env.NODE_AUTH_TOKEN?.trim();
return token ? token : undefined;
}

function resolveOutputDir(
options: IReviewStrongAiPlatformsCliOptions,
strongAiRoot: string,
guardDogRoot: string
strongAiRoot: string
): string {
if (options.outDir) {
return path.resolve(options.outDir);
}
if (options.dryRun) {
return path.join(guardDogRoot, '.guarddog', 'strongai-issue-drafts');
}
return resolveStrongAiIssuesDir(strongAiRoot);
}

Expand Down
2 changes: 1 addition & 1 deletion src/cli/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Review options:
--confirm Confirm GitHub issue creation

StrongAI platform cloud review options:
--dry-run Write drafts under .guarddog/strongai-issue-drafts (no StrongAI/issues write, no sync)
--dry-run Print the cloud review plan only; do not launch agents or send tokens
--sync After writing issues/, invoke StrongAI sync-issues-to-github.sh
--confirm With --sync, actually create GitHub issues (otherwise print the sync command)
--strongai-path <path> Local StrongAI monorepo root (default: STRONGAI_PATH or ../StrongAI)
Expand Down
24 changes: 22 additions & 2 deletions src/core/configLoader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,13 @@ export async function loadConfig(
cliOptions: IReviewCliOptions
): Promise<IGuardDogConfig> {
const fileConfig = await loadConfigFile(repoPath);
const fileIssueMode = readFileIssueMode(fileConfig.github);
const merged: IGuardDogConfig = {
...DEFAULT_CONFIG,
...fileConfig,
github: {
...DEFAULT_CONFIG.github,
...fileConfig.github
enabled: DEFAULT_CONFIG.github.enabled,
issueMode: fileIssueMode ?? DEFAULT_CONFIG.github.issueMode
}
};

Expand Down Expand Up @@ -123,6 +124,25 @@ export async function loadConfig(
return merged;
}

/**
* Reads issue layout from a target repo config.
* `enabled` and `repo` are ignored so the reviewed repository cannot open issues or choose the destination.
* @param github - GitHub section from the config file, if present
*/
function readFileIssueMode(
github: Partial<IGuardDogConfig['github']> | undefined
): IGuardDogConfig['github']['issueMode'] | undefined {
if (!github || typeof github !== 'object' || github.issueMode === undefined) {
return undefined;
}
if (github.issueMode === 'single' || github.issueMode === 'per-finding') {
return github.issueMode;
}
throw new InvalidParameterError(
`Invalid github.issueMode: ${String(github.issueMode)}. Expected single or per-finding.`
);
}

function validateSeverity(value: string, fieldName: string): void {
const allowed = ['low', 'medium', 'high', 'critical'];
if (!allowed.includes(value)) {
Expand Down
25 changes: 13 additions & 12 deletions src/core/designLoader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,21 @@
// ===Start StrongAI Generated Comment (20260524)===
// This module locates and loads an “architecture intent” or design document for a repository. It supports an explicit design file path or a set of default candidate filenames, and returns either the loaded content or a warning describing what was checked.
//
// The main export is loadDesignFile(repoPath, designPath, logger). When designPath is provided, it resolves the path relative to the repo root (or uses it as-is if absolute), attempts to read it, and returns the content plus a normalized repo-relative filename. If the file is missing, it logs a warning and returns only the warning. When designPath is not provided, it iterates through DEFAULT_DESIGN_CANDIDATES under the repo root and returns the first file that exists.
// The main export is loadDesignFile(repoPath, designPath, logger). When designPath is provided, it resolves the path inside the repo root, rejects absolute paths, parent traversal, and symlinks, and returns the content plus a normalized repo-relative filename. Secret-like text, including private key blocks, is redacted before the content is returned. If the file is missing, it logs a warning and returns only the warning. When designPath is not provided, it iterates through DEFAULT_DESIGN_CANDIDATES under the repo root and returns the first file that exists, also redacted.
//
// It returns an IDesignLoadResult containing designFile, designContent, and/or warning.
//
// Key dependencies include Node’s path for path resolution and normalization, readTextFileIfExists for safe file reads, DEFAULT_DESIGN_CANDIDATES for fallback search, and ILogger/defaultLogger for warning output.
// ===End StrongAI Generated Comment===


import * as path from 'path';
import { DEFAULT_DESIGN_CANDIDATES } from '../schemas/config';
import { readTextFileIfExists } from '../utils/fileSystem';
import {
readContainedRepoFile,
redactSecrets,
resolveContainedRepoFile,
toRepoRelativePath
} from '../utils/fileSystem';
import { ILogger, defaultLogger } from '../utils/logger';

export interface IDesignLoadResult {
Expand All @@ -38,25 +42,22 @@ export async function loadDesignFile(
logger: ILogger = defaultLogger
): Promise<IDesignLoadResult> {
if (designPath) {
const resolved = path.isAbsolute(designPath)
? designPath
: path.join(repoPath, designPath);
const content = await readTextFileIfExists(resolved);
const resolved = await resolveContainedRepoFile(repoPath, designPath);
const content = await readContainedRepoFile(repoPath, designPath);
if (!content) {
const warning =
`Design file not found at ${designPath}. Continuing without architecture intent.`;
logger.warn(warning);
return { warning };
}
const relative = path.relative(repoPath, resolved).replace(/\\/g, '/');
return { designFile: relative, designContent: content };
const relative = await toRepoRelativePath(repoPath, resolved);
return { designFile: relative, designContent: redactSecrets(content) };
}

for (const candidate of DEFAULT_DESIGN_CANDIDATES) {
const fullPath = path.join(repoPath, candidate);
const content = await readTextFileIfExists(fullPath);
const content = await readContainedRepoFile(repoPath, candidate);
if (content) {
return { designFile: candidate, designContent: content };
return { designFile: candidate, designContent: redactSecrets(content) };
}
}

Expand Down
Loading
Loading