> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/ci-security.md).

# CI Security: Secret Scanning

## Overview

AI OS uses a defense-in-depth approach to prevent secret leaks. Scanning runs at two layers:

1. **Local pre-commit hook** (`.githooks/pre-commit`) -- blocks staged code and config changes containing real-looking API keys before they reach the remote.
2. **CI secret scan** (`.github/workflows/quality.yml`, `secret-scan` job) -- runs gitleaks on every push and pull request as a second gate.

Both layers are independent. A contributor who skips the local hook (or clones without running `bun install`) is still protected by the CI scan.

## Local Hook

The pre-commit hook at `.githooks/pre-commit` scans staged diffs for provider key prefixes (`pcsk_`, `sk-or-`, `sk-ant-`, `sk-proj-`, `sk_live_`, `apify_api_`) followed by 20+ key-shaped characters, common secret env var assignments with real-looking values (16+ characters), and account-auth JSON token fields.

The hook is activated automatically by the `postinstall` script in `package.json`, which runs `git config --local core.hooksPath .githooks` on every `bun install`.

The local hook intentionally skips lock files, raster/vector assets, Markdown files, and `__tests__/` fixtures. The CI gitleaks scan still covers repository history with `.gitleaks.toml`.

### Bypassing the Local Hook

```bash
git commit --no-verify
```

Use only when the flagged value is a known false positive. If the value is a real secret, rotate it immediately.

## CI Scan (gitleaks)

The `secret-scan` job in `.github/workflows/quality.yml` uses the official `gitleaks/gitleaks-action@v2` action with full history (`fetch-depth: 0`). On pull requests it scans the PR commit range; on pushes to main it scans the push diff.

### Configuration

The gitleaks config lives at `.gitleaks.toml` in the repository root:

* **Default rules**: gitleaks built-in rules are extended (`useDefault = true`).
* **Path exclusions**: lock files, binary assets, `node_modules/`, and `dist/` are excluded from scanning.
* **Regex exclusions**: Placeholder patterns commonly used in docs and examples (`xxx`, `your-*`, `<value>`) are allowed.

### Adding a False-Positive Exclusion

If gitleaks flags a value that is not a real secret:

1. Confirm the value is not sensitive (rotate if unsure).
2. Add a path or regex rule to the `[allowlist]` section of `.gitleaks.toml`.
3. Test locally: `gitleaks detect --config .gitleaks.toml --verbose` (requires gitleaks CLI).
4. Commit the updated `.gitleaks.toml` with a message explaining the exclusion.

### Testing Locally

Install gitleaks and run:

```bash
gitleaks detect --config .gitleaks.toml --verbose
```

This scans the full repository history using the same config as CI.

## Covered Secrets

| Layer       | Provider Keys         | Env Assignments          | Full History     | PR Diff |
| ----------- | --------------------- | ------------------------ | ---------------- | ------- |
| Local hook  | Yes (prefix + length) | Yes (name=value pattern) | No (staged only) | N/A     |
| CI gitleaks | Yes (built-in rules)  | Yes (built-in rules)     | Yes              | Yes     |

## Dependency Audit

The `audit` job in CI runs `bun audit` on every push and PR. This checks all direct and transitive dependencies against known vulnerability databases. A non-zero exit code fails the CI run.

To check locally:

```bash
bun audit
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/ci-security.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.