# Find security issues with Scan

Scan reads a repository for security bugs and lists what it finds, worst first. Each finding explains what is wrong, shows the code it points to, traces step by step how an attacker's input reaches it and can come with a proposed fix. This article explains how Scan works, how to run it in the desktop app, the terminal and CI and what it can't do yet.

> Scan runs in the aixplain desktop app and the `koder` CLI. It arrived in Koder 0.5.1 and was updated in 0.5.2. It is in early releases, so it can change from one release to the next.

## What Scan can do

- **Find likely security bugs:** findings appear as each part of the code is checked, worst first.
- **Explain each finding:** what is wrong, in plain words, with the code it points to.
- **Trace the path:** step by step, how an attacker's input reaches the bug, with a file and line for each step.
- **Propose a fix:** ask for a fix on any finding, then copy the patch and review it like any other change.
- **Continue a stopped scan:** pick up where it stopped, without paying again for the parts already checked.
- **Compare scans:** see what's new, what's fixed and what's still open since the last scan.
- **Gate CI:** write a SARIF report and fail a job at the severity you set.

## How Scan works

Scan splits the code you track in git into areas of a few files each and checks the riskiest areas first, such as request handling, sign-in, shell commands, SQL and file paths. It leaves out tests, fixtures, generated code, translations and vendored folders unless your scan config includes them.

Read-only agents check each area. They can read, search and list files in the project, and nothing else: no shell, no edits and no web access.

Scan reads your code and doesn't run it yet, so every finding is marked **Likely**.

> **Important:** Review each finding before you act on it. A likely issue can turn out to be safe in practice, so check the trace and the code against how your code really runs. Have someone review findings before they block a release.

Scan uses the model you pick, like any Koder task. Each model choice says where your code goes: a model on this computer keeps it there, and other models receive code excerpts. On aixplain models, a scan's spend and limit are shown in credits, in the desktop app and in `koder scan`. Models on your computer have no price, so only the time and agent limits apply.

### Depth and limits

Every depth checks the code the same way. Only the limits change, and you can edit each one.

| Depth | What it checks | Stops after |
|---|---|---|
| Quick | The 40 riskiest areas | $3 or 20 minutes |
| Standard (default) | Every area | $10 or 90 minutes |
| Deep | Every area | $40 or 6 hours |

When a scan reaches a limit, the areas already in progress finish, then it stops. Everything found so far is kept.

## Scan a project in the desktop app

1. Open a project in the sidebar.
2. Select **Security scan** in the project panel, or start a new chat and choose **Check for security bugs**. You can also open the command palette and search for "Scan for security bugs".
3. Select **Start scan**. The page shows the model it will use and when it stops. To pick the model, depth and limits first, select **Change settings**.
4. Open findings as they arrive. Each one shows what is wrong, the code, the trace and the severity.
5. Select **Propose a fix**, then **Copy patch**, or select **Not a real bug** if the finding can't happen.

To stop a scan, select **Stop**. Agents stop right away and everything found so far is kept. Select **Continue** later to check only the areas that are left.

To see what changed after your fixes, run a new scan, open **History** and compare the last two scans.

## Scan a project in the terminal

Install the `koder` CLI as described in **[Get started with Koder](https://www.aixplain.com/support/articles/get-started-with-koder#install-the-cli)**, then run Scan from your project folder:

```sh
koder scan
```

To continue the most recent stopped scan:

```sh
koder scan --continue
```

If the repository has a scan config in `.koder/scan/`, Scan asks you to approve it before it runs, and asks again whenever it changes.

## Run Scan in CI

`koder scan` can write a SARIF report and fail a job when it finds something at or above the severity you set.

```sh
koder scan --ci --sarif report.sarif --fail-on high
```

- `--ci` runs without prompts. If the repository has a scan config, add `--yes` to approve it in the job.
- `--sarif report.sarif` writes the findings to `report.sarif`. Keep it as a build artifact, or pass it to any tool that reads SARIF. Use `--md` or `--json` for a Markdown or JSON report.
- `--fail-on high` fails the job when Scan finds a likely issue at or above high severity. `high` is the default.
- `--incremental` checks only the files changed since the last finished scan.

### Exit codes

| Code | Meaning |
|---|---|
| 0 | Nothing at or above your `--fail-on` severity |
| 1 | At least one likely finding at or above your `--fail-on` severity |
| 2 | The scan couldn't run |
| 3 | A limit stopped the scan, or some areas couldn't be checked |

A Standard scan stops after 90 minutes or $10 by default, which returns 3 and fails the job. Raise the limits with `--minutes` and `--budget-usd`, or pass `--allow-incomplete` to treat a stopped scan as a pass.

### Requirements

- **A supported runner:** macOS (arm64 and x64), Linux (arm64 and x64) or Windows x64, with `curl` and `bash` on macOS and Linux, or PowerShell on Windows.
- **A model the job can use:** set it up as you would on your computer, with aixplain models, your own provider or a local model.

The installer places `koder` in `~/.koder/bin`. A CI step that runs in the same shell may not see the new PATH, so call `~/.koder/bin/koder` directly or add that folder to the job's PATH. To pin a version, download the installer from that release's page on **[GitHub](https://github.com/aixplain/koder/releases)** instead of `latest`.

### Example: a CI step

This is an example of one step. Adapt it to your CI system and the way your jobs provide a model.

```sh
# Install the koder CLI
curl -fsSL https://github.com/aixplain/koder/releases/latest/download/install | bash
export PATH="$HOME/.koder/bin:$PATH"

# Check the install, config and providers
koder doctor

# Scan the files changed since the last scan and fail on high-severity findings
koder scan --ci --incremental --sarif report.sarif --fail-on high
```

## Limitations

- Scan reads the code and doesn't run it yet, so every finding is a likely issue to review.
- It can report a bug that can't happen and can miss real ones. Keep your other security scanners running.
- It checks your own code. Dependency code isn't scanned, and findings that reach into it are listed separately.
- Only files tracked in git are read. Tests, fixtures and generated code are left out unless your scan config includes them.
- A fix comes as a patch to copy. Scan doesn't apply fixes or open pull requests.
- Scheduled scans and alerts aren't available yet.
- This article doesn't cover each CI system's own setup. Run `koder scan --help` for every option in your installed version.

## Frequently asked questions

### Are Scan's findings proven bugs?

No. Scan reads the code and doesn't run it yet, so every finding is marked Likely. Review each one before you act on it.

### Why can't I find Scan in the app?

Open a project in the sidebar first, then select **Security scan**. You can also start a new chat and choose **Check for security bugs**, or search the command palette for "Scan for security bugs".

### What should I do with a finding I think is safe?

Read the trace, check it against how your code really runs and select **Not a real bug** if it can't be reached.

### My scan stopped at a limit. Do I lose what it found?

No. Findings are saved as each area finishes. Select **Continue**, or run `koder scan --continue`, to check the areas that are left without paying again for the ones already checked.

### Does my code leave my computer?

That depends on the model you pick. A model on this computer keeps your code there. Other models receive code excerpts, and the scan setup says which provider.

### Why isn't koder found in my CI job?

Open a new shell, or add `~/.koder/bin` to the job's PATH as in the example.

### Why can't my CI job reach a model?

Run `koder doctor` in the job. It checks the install, config, storage, providers and recent logs.

## Report a security issue in Koder

To report a security issue in Koder itself, email **care@aixplain.com**. Remove credentials and private project data from logs and screenshots first.