Skip to main content
POST
启动代码扫描

权限

需要服务用户或个人访问令牌,并在企业级别拥有 UseAccountCodeScans 权限。

行为

将给定组织中指定代码仓库 (repo_name) 或多个仓库 (repos) 的新代码扫描加入队列。扫描调度程序会异步启动扫描;响应中返回扫描记录,其初始 status 为 waiting 或 pending。轮询 列出代码扫描 以跟踪进度,并在扫描状态变为 completed 后,通过 列出代码扫描发现项 (按 scan_id 过滤) 查看结果。 该扫描归属于调用主体 (即发出请求的服务用户或 PAT) 。

请求字段

必须且只能提供 repo_name 或 repos 中的一个。
  • repo_name:完整的代码仓库名称,例如 owner/repo。该代码仓库必须已可通过组织的 Git 集成访问。
  • host:代码仓库的 Git 主机 (如无法自动推断) 。
  • repos:一次多仓库扫描涵盖的仓库,以对象列表形式提供 (最多 200 个) ,每个对象包含 repo_name 和可选的 host。第一个条目是扫描的主代码仓库。
  • profile_id:要应用的扫描 Profile。对于 ingest 模式的 Profile,请使用启动摄取扫描。
  • scan_type:要运行的扫描类型。提供 profile_id 时,必须与该 Profile 的扫描类型一致。默认为 Profile 的类型;未指定 Profile 时,默认为 security。非安全扫描类型必须指定 Profile。
  • commit_sha:扫描前要检出的 commit。默认为代码仓库默认分支的最新 commit。
  • effort:normal (默认) 采用较低的模型推理强度,并以较大的批次进行调查;deep 运行完整流水线。
  • interactive:设为 true 时,扫描会在威胁建模结束后、调查开始前暂停,进入 awaiting_user_input 状态,供用户审查。默认为 false。只有安全扫描支持交互式审查;其他扫描类型无需用户干预。
  • platform:扫描会话的运行位置,可以是为组织配置的平台标签 (例如 linux、windows 或 macos) ,也可以是 outpost 资源池的名称,不区分大小写。当名称同时匹配平台和 outpost 资源池时,优先选择平台。默认使用组织的默认设置。

错误

  • 当 scan_type 与 Profile 不匹配、未提供 Profile 却指定了非安全类 scan_type,或 platform 与已配置的平台标签或 outpost 资源池不匹配时,返回 400 (错误响应体会列出可用值) 。
  • 当组织仅允许仅摄取扫描,且未提供 ingest 模式的 Profile 时,返回 403。
  • 当企业账户无权查看组织、代码仓库或 Profile 时,返回 404。
  • 当组织的扫描待办列表已满时,返回 409。请稍后重试。
  • 当 repo_name 和 repos 同时提供或均未提供,或 repos 为空时,返回 422。

授权

Authorization
string
header
必填

服务用户凭据(前缀:cog_)

路径参数

org_id
string
必填

组织 ID(前缀:org-)

示例:

"org-abc123def456"

请求体

application/json

用于启动新代码扫描的请求正文。

commit_sha
string | null

扫描前要检出的提交。

effort
enum<string> | null

扫描强度:'normal'(默认)采用较低的模型推理强度,每批调查的规模较大;'deep' 运行完整流水线。

可用选项:
normal,
deep
host
string | null

代码仓库的 Git 主机(如果已知)。

interactive
boolean
默认值:false

为 true 时,扫描会在威胁建模后、调查前暂停,供用户审核。

platform
string | null

扫描会话的运行位置:为组织配置的平台标签(例如 'linux'、'windows'、'macos')或 outpost(BYOB)资源池的名称,不区分大小写;名称同时匹配平台和资源池时,优先使用平台。省略时使用组织默认值。无法识别的值会被拒绝,并返回 400 状态码;错误响应正文会列出可用的平台标签和 outpost 资源池名称。

Maximum string length: 128
profile_id
string | null

要应用于此次扫描的扫描 Profile。

repo_name
string | null

要扫描的代码仓库全名。repo_name 和 repos 必须提供且只能提供其中一个。

repos
ScanRepoRequest · object[] | null

一次扫描涵盖的仓库;第一个条目为该扫描的主要代码仓库。repo_name 和 repos 必须提供且只能提供其中一个。

Maximum array length: 200
scan_type
enum<string> | null

要运行的扫描类型。指定 Profile 时必须与该 Profile 的扫描类型匹配;默认使用该 Profile 的类型,未指定 Profile 的扫描则默认为 'security'。非安全类型必须指定 Profile,否则会被拒绝。

可用选项:
security,
performance,
db-queries,
test-coverage,
dead-code,
code-quality,
cleanup,
telemetry,
accessibility,
compliance,
general,
migration-docs

响应

成功响应

一次代码扫描。

created_at
integer
必填

扫描的创建时间(Unix 秒)。

effort
enum<string>
必填

扫描强度:'normal' 使用较低的模型推理强度,并以较大的批次进行调查;'deep' 运行完整流水线。

可用选项:
normal,
deep
host
string | null
必填

代码仓库的 Git 托管平台(如已知)。

org_id
string
必填

该扫描所属的组织。

profile
CodeScanProfileResponse · object | null
必填

扫描所使用的 Profile(如有)。

repo_name
string
必填

扫描的主代码仓库。多代码仓库扫描还会涵盖此处未列出的其他代码仓库。

scan_id
string
必填

扫描的唯一标识符。

scan_type
enum<string>
必填

扫描类型,在创建时确定。

可用选项:
security,
performance,
db-queries,
test-coverage,
dead-code,
code-quality,
cleanup,
telemetry,
accessibility,
compliance,
general,
migration-docs
status
enum<string>
必填

扫描状态:waiting、pending、running、awaiting_user_input、completed、failed 或 cancelled。

可用选项:
waiting,
pending,
running,
awaiting_user_input,
completed,
failed,
cancelled
url
string
必填

Devin webapp 中扫描页面的 URL。

outpost_pool_id
string | null

运行扫描会话的 outpost 资源池(若已设置)。

platform
string | null

运行扫描会话的托管平台标签。扫描在 outpost 资源池或组织默认环境中运行时为 Null。

repo_full_name
string | null

包含主机名的主要代码仓库标识(例如 github.com/org/repo)。Perforce depot 没有 Git 主机,因此为 Null。