# How the Archon Env-Leak Scanner Detects Sensitive Variables in .env Files

> Discover how the Archon env-leak scanner identifies sensitive variables in .env files. This utility parses key-value pairs, flagging exposed API keys and other secrets to enhance your security.

- Repository: [Cole Medin/Archon](https://github.com/coleam00/Archon)
- Tags: how-to-guide
- Published: 2026-04-10

---

**The Archon env-leak scanner is a pure-function utility in [`packages/core/src/utils/env-leak-scanner.ts`](https://github.com/coleam00/Archon/blob/main/packages/core/src/utils/env-leak-scanner.ts) that iterates over auto-loaded dotenv files, parses key-value pairs, and flags any variables matching a predefined set of sensitive keys like `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`.**

Archon is an open-source AI coding assistant that prevents accidental credential exposure by scanning environment files before project registration. The **env-leak scanner** specifically targets standard Node.js dotenv auto-load patterns to ensure API keys and authentication tokens never leak into managed configurations.

## What Defines a "Sensitive" Key

According to the Archon source code, sensitivity is determined by exact string matching against a hardcoded Set defined at the top of **[`env-leak-scanner.ts`](https://github.com/coleam00/Archon/blob/main/env-leak-scanner.ts)** ([lines 4‑12](https://github.com/coleam00/Archon/blob/dev/packages/core/src/utils/env-leak-scanner.ts#L4-L12)):

```typescript
export const SENSITIVE_KEYS = new Set([
  'ANTHROPIC_API_KEY',
  'ANTHROPIC_AUTH_TOKEN',
  'CLAUDE_API_KEY',
  'CLAUDE_CODE_OAUTH_TOKEN',
  'OPENAI_API_KEY',
  'CODEX_API_KEY',
  'GEMINI_API_KEY',
]);

```

Any environment variable key that exactly matches one of these seven strings triggers a leak finding. The use of a `Set` structure ensures **O(1)** lookup time during the scan.

## Which Files the Scanner Inspects

Archon does not scan arbitrary files. It strictly examines the filenames that Node.js automatically loads as environment configuration, as defined in **[`env-leak-scanner.ts`](https://github.com/coleam00/Archon/blob/main/env-leak-scanner.ts)** ([lines 14‑21](https://github.com/coleam00/Archon/blob/dev/packages/core/src/utils/env-leak-scanner.ts#L14-L21)):

```typescript
export const AUTOLOADED_FILES = [
  '.env',
  '.env.local',
  '.env.development',
  '.env.production',
  '.env.development.local',
  '.env.production.local',
];

```

The scanner iterates over this array in order, constructing absolute paths relative to the target directory passed to the scan function.

## The Scanning Algorithm

The core logic resides in `scanPathForSensitiveKeys(dirPath)`, exported from **[`env-leak-scanner.ts`](https://github.com/coleam00/Archon/blob/main/env-leak-scanner.ts)** ([lines 59‑91](https://github.com/coleam00/Archon/blob/dev/packages/core/src/utils/env-leak-scanner.ts#L59-L91)). This function returns a `LeakReport` object containing any detected exposures.

### Step-by-Step Execution

1. **Path Resolution**: For each filename in `AUTOLOADED_FILES`, the scanner joins it with the provided `dirPath` using `join()`.

2. **Existence Check**: Uses `existsSync(fullPath)` to skip missing files silently.

3. **File Reading**: Reads the file via `readFileSync(fullPath, 'utf8')`. If reading fails (permissions, encoding issues), the scanner captures the error code and records the file as `[unreadable — ${code}]` in the findings.

4. **Line Parsing**: Splits the file contents by newline and processes each line:
   - Trims whitespace
   - Ignores lines starting with `#` (comments)
   - Ignores lines without an `=` character
   - Extracts the substring before the first `=` as the key name

5. **Key Matching**: Checks if the extracted key exists in `SENSITIVE_KEYS` using `.has()`.

6. **Report Generation**: Accumulates matches into a `LeakFinding` array. If at least one sensitive key is found, the file is added to the `findings` property of the returned `LeakReport`.

The `LeakReport` interface ([lines 28‑31](https://github.com/coleam00/Archon/blob/dev/packages/core/src/utils/env-leak-scanner.ts#L28-L31)) structures the results:

```typescript
export interface LeakReport {
  path: string;
  findings: LeakFinding[];
}

```

## Error Handling and User Context

When `scanPathForSensitiveKeys()` returns findings, Archon throws an **`EnvLeakError`** that formats context-specific messages based on the call site—whether the scan originated from the UI registration flow, CLI auto-register, or a pre-spawn check. This ensures users see relevant instructions for their specific interface when a leak is detected.

The error formatting logic resides in the same file immediately after the scanner implementation, handling edge cases like unreadable files by preserving the Node.js error code in the report output.

## Implementation Examples

### Scanning a Project Directory Directly

```typescript
import { scanPathForSensitiveKeys } from '@archon/core/src/utils/env-leak-scanner';

const report = scanPathForSensitiveKeys(process.cwd());

if (report.findings.length === 0) {
  console.log('✅ No sensitive keys found in .env files.');
} else {
  console.error('⚠️  Sensitive environment variables detected:');
  for (const f of report.findings) {
    console.error(`  • ${f.file}: ${f.keys.join(', ')}`);
  }
}

```

Example output when leaks are found:

```

⚠️  Sensitive environment variables detected:
  • .env: OPENAI_API_KEY, CLAUDE_API_KEY

```

### Integrating with Registration Flows

Before persisting a new codebase, registration commands call the scanner and throw `EnvLeakError` if violations exist:

```typescript
import { EnvLeakError, scanPathForSensitiveKeys } from '@archon/core/src/utils/env-leak-scanner';
import { registerCodebase } from '@archon/core/src/commands/register';

async function registerWithLeakCheck(path: string) {
  const report = scanPathForSensitiveKeys(path);
  if (report.findings.length) {
    throw new EnvLeakError(report, 'register-cli');
  }
  await registerCodebase(path);
}

```

Higher-level UI and CLI handlers catch this error to present consent prompts or blocking dialogs based on the `context` parameter passed to the constructor.

## Summary

- **Hardcoded Sensitivity**: Archon uses a `Set` named `SENSITIVE_KEYS` in [`env-leak-scanner.ts`](https://github.com/coleam00/Archon/blob/main/env-leak-scanner.ts) to define exactly seven sensitive variable names, including `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`.
- **Strict File targeting**: Only the six standard Node.js dotenv filenames listed in `AUTOLOADED_FILES` are inspected.
- **Synchronous Parsing**: The scanner uses `readFileSync` and manual line splitting to extract keys left of the `=` character, skipping comments and malformed lines.
- **Structured Reporting**: Results return via a `LeakReport` interface containing `LeakFinding` objects with filename and key arrays.
- **Contextual Errors**: When leaks are detected, `EnvLeakError` provides interface-specific messaging for UI, CLI, or pre-spawn contexts.

## Frequently Asked Questions

### What specific API keys does Archon consider sensitive?

Archon flags seven specific environment variables: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `OPENAI_API_KEY`, `CODEX_API_KEY`, and `GEMINI_API_KEY`. These are hardcoded in the `SENSITIVE_KEYS` Set inside [`packages/core/src/utils/env-leak-scanner.ts`](https://github.com/coleam00/Archon/blob/main/packages/core/src/utils/env-leak-scanner.ts).

### How does Archon handle unreadable .env files?

If `readFileSync` throws an error due to permissions or encoding issues, the scanner catches the exception, extracts the Node.js error code, and records a finding with the key listed as `[unreadable — ${code}]`. This ensures users are alerted to potential secrets even when file contents cannot be parsed.

### Can I customize which variables the env-leak scanner flags?

Currently, the scanner does not support runtime configuration of sensitive keys. The `SENSITIVE_KEYS` Set is exported as a constant and would require modification of the source code in [`packages/core/src/utils/env-leak-scanner.ts`](https://github.com/coleam00/Archon/blob/main/packages/core/src/utils/env-leak-scanner.ts) to add or remove variables from the detection list.

### When does the env-leak scan actually execute?

Archon triggers the scan during codebase registration flows—whether initiated through the web UI, CLI commands, or automated setup processes. The scan runs before any persistence occurs, throwing `EnvLeakError` if sensitive variables are detected, thereby blocking registration until the issue is resolved.