Security Scan

Qoder Agent SDK ships built-in code security capabilities, so an agent can check its own output as it writes and modifies code, and audit a whole repository on demand — keeping a security floor under an automated workflow. All three switches are off by default. Security scanning consumes additional turns and credits, so it is never enabled implicitly; the application opts in per session. Both SDKs support this option. TypeScript uses securityScan with camelCase switches; Python uses security_scan with snake_case switches.

The three levels

The three levels are independent. Enable only what the workflow needs.

Switch (TypeScript / Python)	Scope	Runs when
`l1StaticCheck` / `l1_static_check`	The file the agent just changed	Automatically, after supported file edits
`l2LightweightScan` / `l2_lightweight_scan`	The repository, shallow pass	When the agent decides a scan is warranted
`l3DeepScan` / `l3_deep_scan`	The repository, deep pass	When the agent decides a deep audit is warranted

l1StaticCheck is a backstop on the agent's own edits and adds the least overhead. l2LightweightScan and l3DeepScan grant the agent the ability to scan the repository; they do not force a scan on every turn.

Enable scanning

import { query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: 'Implement the password reset endpoint',
  options: {
    securityScan: {
      l1StaticCheck: true,
      l2LightweightScan: true,
    },
  },
})) {
  console.log(message);
}

A common way to stage them:

Feature work: enable l1StaticCheck only, so the agent covers its own edits without noticeably extending a turn.
Pre-merge review: add l2LightweightScan.
Scheduled audits: add l3DeepScan, run by a job with enough time budget.

The option overrides settings, it does not merge

Once securityScan is provided, it governs the session: any securityScan block in a settings file or settings object is discarded in full, and every switch not listed explicitly is set to false.

// settings.json contains: { "securityScan": { "l1StaticCheck": true } }

options: {
  settings: './settings.json',
  securityScan: { l3DeepScan: true },
}

// Effective result — l1StaticCheck is now off:
// { l1StaticCheck: false, l2LightweightScan: false, l3DeepScan: true }

The same rule applies to security_scan in Python. Other settings keys are unaffected; only the securityScan block is replaced. To keep a switch enabled, declare it again in the option. Omit securityScan entirely to let settings files decide.

Validation happens before the process starts

Invalid values raise immediately, before Qoder CLI starts — a misspelled switch surfaces on the spot instead of being silently ignored.

options: { securityScan: { l2LightweightScann: true } }
// TypeError: securityScan contains unknown option: l2LightweightScann

options: { securityScan: { l1StaticCheck: 'yes' } }
// TypeError: securityScan.l1StaticCheck must be a boolean

Verify it took effect

Enabling any switch exposes the built-in security-scan capability to the session. Read it back from the initialization result:

const q = query({ prompt: userMessages(), options: { securityScan: { l2LightweightScan: true } } });

const init = await q.initializationResult();
const enabled = init.skills?.some(
  (skill) => skill.name === 'security-scan' && skill.source === 'built-in',
);
console.log(enabled); // true

With no securityScan option, that entry is absent.

Scanning is not permission control

These two mechanisms answer different questions, and one does not substitute for the other:

Mechanism	Question it answers
`securityScan`	Can the agent inspect code for vulnerabilities?
Permissions	Is the agent allowed to run this tool or touch this path?

Security scanning finds problems in code. It does not constrain what the agent may do. An agent with l3DeepScan enabled and no permission policy can still run arbitrary commands. Set both.

Next steps

Permission Control — restrict which tools and paths the agent can reach
Hooks — block or rewrite a tool call before it runs
Skills — control which capabilities the session exposes to the model

​The three levels

​Enable scanning

​The option overrides settings, it does not merge

​Validation happens before the process starts

​Verify it took effect

​Scanning is not permission control