audit-workflow

name	audit-workflow
description	Full code audit workflow - from adding a repo to reviewing vulnerabilities and filing issues
version	2.0.0
author	kai-agent
metadata	{"kai":{"tags":["kai","security","audit","vulnerabilities"]}}

Code Audit Workflow

End-to-end workflow for running a Kai code audit on a repository.

Prerequisites

• Kai MCP tools available (connected to Kai backend)
• Active agent subscription on the workspace

Workflow

1. Set up the workspace context

list_my_workspaces → pick the target workspace
list_repositories → check if the repo is already added

If the repo is not added:

add_github_repository(workspaceId, owner, repo, branch)

If no repos are connected at all, check what the user has on GitHub:

list_github_user_repos → show available repos and help connect one

2. Choose audit depth

list_audit_tiers → review available audit depths

Never expose tier IDs to the user. Offer simple choices: quick, standard, or deep. Map to the correct tier internally.

3. Start the audit

start_code_audit(workspaceId, repoId, tierId)
→ returns executionId

Always confirm with the user before starting.

4. Monitor progress

Poll periodically (every 30-60 seconds for active monitoring):

get_code_audit_details(executionId) → check status
get_audit_progress_logs(executionId) → see agent iterations

Report significant milestones to the team:

• Audit started (with depth and estimated duration)
• First vulnerability found
• Audit completed (with summary stats)

5. Review findings

list_vulnerabilities(executionId) → get all findings
get_vulnerability_details(executionId, exploitId) → deep dive on each

For each vulnerability, note:

• Severity (critical, high, medium, low)
• Affected file and function
• Whether it was verified (execution-based verification = zero false positives)
• Attack hypothesis and PoC
• Suggested fix

6. Take action

The integrations MCP category owns all GitHub/Jira write tools — call activate_category('integrations') once before any of the steps below.

For every verified vulnerability: file an issue via the scan-derived wrapper, which auto-renders the issue body from exploit data:

create_github_security_issue(workspaceId, executionId, exploitId)

or

create_jira_security_ticket(workspaceId, executionId, exploitId)

For vulnerabilities with a clear, small, high-confidence fix: also ship the fix as a PR.

The issue and the PR are not either/or — the issue is the public finding record, the PR is the remediation. Both link back to the same lifecycle action so the dashboard shows finding → action → issue + PR → merged.

# 1. Propose remediation as a lifecycle action the user approves
lifecycle_actions_create(
  workspaceId, type="remediate",
  title="Fix CVE-2022-23529 in payment-service",
  description="Upgrade jsonwebtoken 8.5.1 → 9.0.0 (see issue #142). One-line dep bump + re-run existing tests.",
  priority="critical",
  repoId=<repoId>,
  linkedItems=[
    {"platform": "github", "externalId": "acme/payment-service#142", "url": "...", "title": "CVE-2022-23529"},
  ],
)
# → wait for status=approved; do NOT re-ask for confirmation

# 2. Compose the fix by reading the current files
read_repository_files(workspaceId, repoId, paths=["package.json", "src/auth/webhook.ts", ...])

# 3. Open the PR — backend creates the branch, commits, opens the PR
create_pull_request(
  workspaceId, repoId,
  base="main",
  branchName="fix/cve-2022-23529",
  title="fix: upgrade jsonwebtoken to 9.0.0 (closes CVE-2022-23529)",
  body="Closes #142. Verified exploit no longer triggers against the upgraded dep.",
  changes=[
    {"path": "package.json", "operation": "update", "content": <full new content>},
    ...
  ],
  labels=["security"],
  linkedItems=[
    {"platform": "github", "externalId": "acme/payment-service#142", "url": "...", "title": "CVE-2022-23529"},
    {"platform": "kai",    "externalId": actionId, "url": f"kai://actions/{actionId}"},
  ],
)

# 4. Monitor CI, iterate if needed
list_pull_request_checks(workspaceId, repoId, number=<pr_number>)
# If a check fails: fetch logs, compose the fix, push via update_pull_request_branch. Max 3 auto-fix attempts.

When NOT to ship a PR (file the issue only and stop):

• The fix touches .github/workflows/* — the GitHub App doesn't hold Workflows: Write (by design). File an issue describing the exact workflow edit needed and link it to the main remediation.
• The fix spans >20 files or touches architectural boundaries — propose a plan in the issue, don't try to land it in one shot.
• The root cause is unclear — investigate first, propose a fix only when you understand the scope.
• The vulnerability is reachable only in a config state the user would need to confirm (feature flag, environment variable) — file the issue, wait for direction.

Full PR workflow (monitoring, iteration, merge) is in skills/github/github-pr-workflow.

7. Report to team

Summarize findings with:

• Total vulnerabilities found (by severity)
• Most critical findings with brief descriptions
• Recommended priority for fixes

Tips

• Save workspace and repo IDs in memory after first discovery to skip lookup next time
• For repos with many files, browse the file tree first to understand structure
• If an audit takes too long, check progress logs for stuck agents
• Compare findings across multiple audits to track security posture over time