Valca

io.github.pranlabsv0.6.1更新于 Oct 7, 2026

Scans code, IaC and AI-agent config for security problems. Read-only — nothing can be edited.

已验证STDIO仅桌面Developer Tools Security & Monitoring

概览

AI 生成的概览

让助手对代码、IaC 和 AI 代理配置执行只读安全扫描，返回发现项和规则目录。

功能: Valca 提供两个只读工具：scan(path) 返回文件或目录的发现项，包括规则 ID、严重级别、消息、文件、行号和修复建议；list_rules() 返回完整规则目录，含每条规则的 ID、严重级别和检测内容。覆盖密钥、GitHub Actions、Docker、Docker Compose、Terraform、Kubernetes、提示注入、依赖完整性等。没有任何工具会编辑、修复或写入内容。
适用场景: 适合在会话中让助手检查代码或基础设施文件的安全问题，例如审查 Docker Compose 文件、Terraform 模块或 GitHub Actions 工作流。它是独立写入时钩子的只读补充，钩子才是强制路径；MCP 服务器由代理自行选择启用。
运行要求: 通过 uvx 从 PyPI 包 valca 启动的本地进程，需安装 mcp 附加组件。未声明账户、API 密钥或请求头。扫描范围限于 valca-mcp 启动时的目录，或由 VALCA_MCP_ROOT 指定。仅依赖规则需要网络，会把包名和版本字符串发送到 api.osv.dev、pypi.org 和 registry.npmjs.org。

安装前请注意

只读：没有工具会编辑、修复或写入。匹配到的源码行不会返回，因此不会暴露密钥值。路径以扫描根目录的相对形式返回。依赖规则（VGL-PKG001 至 VGL-PKG004）会把包名和版本字符串发送给第三方主机；在 .valcarc 中禁用它们即可完全离线运行。此路径下遥测已关闭。

安装

在 SourceWeft 中

打开控制台中的 Valca，将其添加到工作区。
为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照仓库中的启动说明。

README

Valca

AI coding security co-pilot — blocks insecure code at the moment of generation.

Formerly published as vigilsec. The package is now valca. Both the valca and vigil commands work, so existing hooks and scripts keep running unchanged.

Valca intercepts every file an AI coding assistant writes and blocks it if CRITICAL or HIGH security findings are detected — before the file hits disk. It's the only tool that operates at generation time rather than post-commit.

The Problem

AI coding assistants reproduce the most common patterns in their training data. The most common patterns are insecure defaults.

The clearest example: every existing IaC scanner (Checkov, Trivy, Snyk, Semgrep) misses the docker-compose port binding that exposes your database to the internet:

The correct form is "127.0.0.1:5432:5432". Valca catches it. Nothing else does.

Install

Wire the Claude Code hook (one time):

That's it. Every file Claude Code writes is now scanned before it saves. Reload Claude Code to activate.

Network access

Valca's core scanning is fully offline — the package has zero runtime dependencies and the engine never sends your code, file paths, or findings anywhere.

Three rules do reach the network, because checking whether a dependency is vulnerable or fabricated is impossible offline. When a manifest (requirements.txt, package.json, lockfiles) is scanned, these rules send package names and version strings only to:

Host	Used by	What is sent
`api.osv.dev`	VGL-PKG001 (known CVE in a pinned version)	package name + version
`pypi.org`	VGL-PKG002/003/004 (hallucinated, stale, or suspicious package)	package name
`registry.npmjs.org`	VGL-PKG002/003/004	package name

Your source code, file contents, file paths, and scan results are never transmitted. If your dependency inventory is itself sensitive, turn these rules off in .valcarc and Valca runs completely offline:

Usage

bash

# Scan a single filevalca scan docker-compose.yml
# Scan a directoryvalca scan ./my-project/
# JSON output (for CI / dashboards)valca scan ./my-project/ --format json
# SARIF output (for GitHub Advanced Security)valca scan ./my-project/ --format sarif > results.sarif
# Only report HIGH and abovevalca scan ./my-project/ --severity HIGH
# Open feedback & waitlist formvalca feedback

# Scan a single filevalca scan docker-compose.yml
# Scan a directoryvalca scan ./my-project/
# JSON output (for CI / dashboards)valca scan ./my-project/ --format json
# SARIF output (for GitHub Advanced Security)valca scan ./my-project/ --format sarif > results.sarif
# Only report HIGH and abovevalca scan ./my-project/ --severity HIGH
# Open feedback & waitlist formvalca feedback

Review what has been caught over time. Both commands read the local scan history — nothing leaves your machine.

bash

# Findings log — what was caught, where, and whenvalca log                              # 20 most recent findingsvalca log --severity CRITICAL          # only criticalsvalca log --project api --since 2026-09-01valca log --limit 100 --format json    # for dashboards
# Aggregate stats — rule frequency, severity mix, precision per rulevalca statsvalca stats --format json

# Findings log — what was caught, where, and whenvalca log                              # 20 most recent findingsvalca log --severity CRITICAL          # only criticalsvalca log --project api --since 2026-09-01valca log --limit 100 --format json    # for dashboards
# Aggregate stats — rule frequency, severity mix, precision per rulevalca statsvalca stats --format json

valca stats reports how often each rule fires and how often you suppressed it, so rules with poor precision in your codebase are visible rather than guessed at.

Exit codes:

See It in Action

Blocking a vulnerable GitHub Actions workflow at write time:

[Valca blocking a Comment-and-Control attack]

In April 2026, researchers found that all three major AI coding agents (Claude Code, Gemini CLI, Copilot) could be hijacked to exfiltrate ANTHROPIC_API_KEY and GITHUB_TOKEN via a hidden HTML comment in a GitHub issue. CVSS 9.4. No special access required.

Valca catches the vulnerable workflow (issues: trigger + AI agent + API key in env) before it reaches git — the only tool that does.

→ Full writeup: The Attack That Steals Your API Keys Through a GitHub Issue Comment

Rules

116 rules across 27 categories. All built-in, stdlib-only, zero runtime dependencies.

This catalogue is generated from the rule registry — it cannot drift from the shipped engine.

Secrets & Credential Exposure (14 rules)

Rule	Severity	What it catches
VGL-I001	CRITICAL	eval() or exec() — code injection risk
VGL-I002	HIGH	subprocess with shell=True
VGL-I003	HIGH	os.system() call
VGL-S001	CRITICAL	AWS access key hardcoded
VGL-S002	CRITICAL	Hardcoded password
VGL-S003	CRITICAL	Hardcoded API key
VGL-S004	CRITICAL	Hardcoded bearer token
VGL-S005	CRITICAL	Hardcoded JWT secret
VGL-S006	CRITICAL	PEM private key in source
VGL-S007	CRITICAL	Database URL with embedded credentials
VGL-S008	CRITICAL	Stripe live secret key
VGL-S009	CRITICAL	Slack token hardcoded
VGL-S010	CRITICAL	Provider API key hardcoded (OpenAI / GitHub / GitLab / Google)
VGL-S012	HIGH	Insecure placeholder default for security-critical config

GitHub Actions — AI Agent Surface (13 rules)

Rule	Severity	What it catches
VGL-GHA001	CRITICAL	Pwn Request — pull_request_target with attacker-controlled checkout ref
VGL-GHA002	CRITICAL	Script injection — user-controlled context expression in run: step
VGL-GHA004	HIGH	Secret directly interpolated in run: step (visible in process table)
VGL-GHA005	MEDIUM	Workflow missing explicit permissions block (implicit GITHUB_TOKEN scope)
VGL-GHA006	HIGH	Cache usage in pull_request workflow (cache poisoning attack vector)
VGL-GHA007	HIGH	Self-hosted runner with pull_request trigger (persistent runner risk)
VGL-GHA008	HIGH	workflow_run trigger without ref/repo validation
VGL-GHA009	CRITICAL	AI agent wired to untrusted-input trigger (issues/pull_request_target) with API key in env
VGL-GHA010	HIGH	AI agent on pull_request_target without fork origin guard
VGL-GHA011	CRITICAL	Untrusted GitHub event data interpolated into AI agent prompt
VGL-GHA012	HIGH	AI agent on untrusted trigger with no --allowedTools restriction
VGL-GHA013	MEDIUM	AI agent on untrusted trigger with no --max-turns limit
VGL-GHA014	HIGH	contents: write permission with AI agent on untrusted trigger

AI Agent — Prompt Injection (9 rules)

Rule	Severity	What it catches
VGL-PI001	CRITICAL	User input interpolated into the LLM system prompt
VGL-PI002	HIGH	Raw HTTP request body used as LLM message content
VGL-PI003	HIGH	String formatting used to build prompts with user data
VGL-PI004	MEDIUM	Tool output appended to the conversation without sanitization
VGL-PI005	CRITICAL	HTTP request data flows into an LLM prompt unsanitised
VGL-PI006	CRITICAL	LLM response flows into subprocess, exec or eval
VGL-PI007	HIGH	Webhook payload flows directly into an AI agent
VGL-PI008	HIGH	Database content interpolated into a prompt — second-order injection
VGL-PI009	HIGH	User input written into a vector store — memory poisoning

Dockerfile Hardening (8 rules)

Rule	Severity	What it catches
VGL-DF001	HIGH	Dockerfile runs as root — no USER directive
VGL-DF002	MEDIUM	Dockerfile uses unpinned :latest base image
VGL-DF003	HIGH	Dockerfile bakes secret into ENV or ARG layer
VGL-DF004	HIGH	curl
VGL-DF005	HIGH	TLS verification disabled in Dockerfile RUN fetch
VGL-DF006	MEDIUM	ADD used for local files — use COPY instead
VGL-DF007	HIGH	COPY . without .dockerignore — risks leaking .git, .env, credentials
VGL-DF008	MEDIUM	World-writable permissions set in Dockerfile (chmod 777)

Docker Compose (7 rules)

Rule	Severity	What it catches
VGL-D001	CRITICAL	Docker public port binding — bypasses UFW, exposes service to internet
VGL-D002	HIGH	docker-compose environment block contains hardcoded secret
VGL-D003	CRITICAL	Docker container runs in privileged mode
VGL-D004	HIGH	Docker container uses host network mode
VGL-D005	CRITICAL	Docker socket mounted into container — full container escape vector
VGL-D006	HIGH	Sensitive host path mounted into container
VGL-D007	HIGH	AWS credentials directory (~/.aws) mounted into container — exposes all profiles

Terraform (7 rules)

Rule	Severity	What it catches
VGL-TF001	CRITICAL	Terraform hardcoded secret value
VGL-TF002	HIGH	Terraform resource with public access enabled
VGL-TF003	HIGH	Terraform encryption explicitly disabled
VGL-TF004	CRITICAL	IMDSv1 enabled on EC2 instance — vulnerable to SSRF metadata theft
VGL-TF005	HIGH	Terraform S3 state backend stored without encryption
VGL-TF006	MEDIUM	Deletion protection disabled on managed resource
VGL-TF007	MEDIUM	Audit logging disabled on Terraform-managed resource

Deserialization & Path Traversal (5 rules)

Rule	Severity	What it catches
VGL-DESER001	CRITICAL	Insecure deserialization — pickle.loads / pickle.load
VGL-DESER002	HIGH	Insecure YAML deserialization — yaml.load() without SafeLoader
VGL-DESER003	HIGH	Insecure deserialization — marshal.loads with untrusted data
VGL-PATH001	HIGH	Path traversal — user input passed to file open or path join without validation
VGL-SSTI001	CRITICAL	Server-Side Template Injection — user input rendered as Jinja2 template

MCP Server Security (5 rules)

Rule	Severity	What it catches
VGL-MCP001	CRITICAL	Prompt injection embedded in MCP tool description
VGL-MCP002	HIGH	MCP tool description built from user-controlled data
VGL-MCP003	HIGH	Shell execution in an MCP tool handler without a sandbox
VGL-MCP004	HIGH	MCP server config uses an unpinned package or plaintext HTTP endpoint
VGL-MCP005	HIGH	MCP fetch tool takes an agent-controlled URL with no allowlist

Web Application Security (5 rules)

Rule	Severity	What it catches
VGL-CORS001	HIGH	CORS wildcard — allow_origins=['*']
VGL-SQL001	CRITICAL	SQL injection — query built with f-string or string concatenation
VGL-SQL002	CRITICAL	SQL injection — ORM raw query with f-string
VGL-SSL001	HIGH	SSL verification disabled
VGL-SSRF001	CRITICAL	SSRF — HTTP call with user-controlled URL

AI Agent — Excessive Agency (4 rules)

Rule	Severity	What it catches
VGL-A001	CRITICAL	LLM output piped into shell execution
VGL-A002	HIGH	Hardcoded auto-approval disables human-in-the-loop
VGL-A003	HIGH	Unbounded agent loop with no iteration limit
VGL-A004	HIGH	LLM response written to disk without validation

Authentication & Session (4 rules)

Rule	Severity	What it catches
VGL-AUTH001	CRITICAL	JWT algorithm=none — signature verification bypassed
VGL-AUTH002	CRITICAL	JWT verify_signature disabled — any token accepted
VGL-AUTH003	HIGH	Weak or hardcoded web framework secret key
VGL-AUTH004	HIGH	Debug mode enabled in framework code

Dependency Integrity (4 rules)

Rule	Severity	What it catches
VGL-PKG001	CRITICAL	Package audit (CVE · hallucination · staleness · supply chain)
VGL-PKG002	CRITICAL	Package not found on registry — hallucinated or slopsquatting target
VGL-PKG003	HIGH	Package version significantly behind latest — stale AI training data
VGL-PKG004	HIGH	Package newly registered with few releases — supply-chain risk

Kubernetes (4 rules)

Rule	Severity	What it catches
VGL-K001	CRITICAL	Privileged container or host namespace access
VGL-K002	CRITICAL	allowPrivilegeEscalation enabled in Kubernetes securityContext
VGL-K003	HIGH	Dangerous Linux capabilities added in Kubernetes securityContext
VGL-K004	HIGH	Sensitive hostPath volume in Kubernetes manifest

Logging & Data Exposure (4 rules)

Rule	Severity	What it catches
VGL-LOG001	HIGH	Sensitive data written to logs (CWE-532)
VGL-LOG002	HIGH	Error details leaked in HTTP response body (CWE-209)
VGL-LOG003	MEDIUM	Silent exception swallowing in authentication/security context
VGL-LOG004	MEDIUM	CRLF injection risk — user-controlled input logged without newline sanitization

Swift / iOS (4 rules)

Rule	Severity	What it catches
VGL-SW001	CRITICAL	Hardcoded secret in Swift string literal
VGL-SW002	HIGH	Plain HTTP URL in Swift networking code
VGL-SW003	HIGH	Sensitive value written to UserDefaults (unencrypted)
VGL-SW004	CRITICAL	SSL certificate validation bypassed in URLSession delegate

Dependency CVE Scanners (3 rules)

GitHub Actions — Workflow Hygiene (3 rules)

Rule	Severity	What it catches
VGL-GH001	HIGH	GitHub Actions secret printed in run step (log exposure)
VGL-GH002	HIGH	GitHub Actions workflow with excessive permissions
VGL-GH003	HIGH	GitHub Actions uses mutable action ref (tag or branch)

AI Agent — Configuration Files (2 rules)

JavaScript / TypeScript (2 rules)

Row-Level Security (2 rules)

Cross-Site Scripting (1 rule)

Cryptography (1 rule)

IAM Policies (1 rule)

Python (1 rule)

Shell Scripts (1 rule)

Trivy IaC Deep Scan (1 rule)

nginx (1 rule)

Configuration

Place a .valcarc file in your project root (or any ancestor directory):

toml

# .valcarcdisabled_rules = ["VGL-T001"]        # skip trivy scan for this projectmin_severity   = "HIGH"              # only report HIGH and aboveexclude_paths  = ["vendor", "legacy"]telemetry      = false               # opt out of anonymous local telemetry

# .valcarcdisabled_rules = ["VGL-T001"]        # skip trivy scan for this projectmin_severity   = "HIGH"              # only report HIGH and aboveexclude_paths  = ["vendor", "legacy"]telemetry      = false               # opt out of anonymous local telemetry

Valca walks up the directory tree to find the nearest .valcarc (the former .vigilrc name is still read). Child config always wins over parent. Monorepos can have per-project overrides alongside a workspace default.

Inline suppression — for a specific line you've reviewed and accepted:

Same pattern as # noqa (flake8) and # nosec (bandit).

Opt-out

Valca collects anonymous, local-only telemetry: rule ID, severity, and file extension. No file paths, no code, no identifiable data. Stored at ~/.valca/events.jsonl — never sent anywhere. History from the former ~/.vigil/ location is migrated automatically.

Opt out permanently:

Or in .valcarc:

Adding a Rule

python

# src/valca/rules/my_category.pyfrom pathlib import Pathfrom .base import Finding, Rule, Severity
class MyRule(Rule):    id = "VGL-X001"    name = "Descriptive rule name"    severity = Severity.HIGH
    def applies_to(self, path: Path) -> bool:        return path.suffix == ".yml"
    def check(self, path: Path) -> list[Finding]:        findings = []        for i, line in enumerate(path.read_text().splitlines(), 1):            if "bad_pattern" in line:                findings.append(Finding(                    rule_id=self.id,                    severity=self.severity,                    message="Found bad pattern",                    file_path=path,                    line=i,                    snippet=line.strip(),                    fix="Do this instead.",                ))        return findings

# src/valca/rules/my_category.pyfrom pathlib import Pathfrom .base import Finding, Rule, Severity
class MyRule(Rule):    id = "VGL-X001"    name = "Descriptive rule name"    severity = Severity.HIGH
    def applies_to(self, path: Path) -> bool:        return path.suffix == ".yml"
    def check(self, path: Path) -> list[Finding]:        findings = []        for i, line in enumerate(path.read_text().splitlines(), 1):            if "bad_pattern" in line:                findings.append(Finding(                    rule_id=self.id,                    severity=self.severity,                    message="Found bad pattern",                    file_path=path,                    line=i,                    snippet=line.strip(),                    fix="Do this instead.",                ))        return findings

Then add it to DEFAULT_RULES in src/valca/rules/__init__.py. Write tests. Done.

GitHub Actions

Use the action — PranLabs/valca-action:

yaml

permissions:  contents: read  security-events: write
steps:  - uses: actions/checkout@v7
  - uses: PranLabs/valca-action@v1    with:      severity: HIGH      version: "0.6.0"    # pin for reproducible CI
  - uses: github/codeql-action/upload-sarif@v4    if: always()    with:      sarif_file: valca-results.sarif      category: valca

permissions:  contents: read  security-events: write
steps:  - uses: actions/checkout@v7
  - uses: PranLabs/valca-action@v1    with:      severity: HIGH      version: "0.6.0"    # pin for reproducible CI
  - uses: github/codeql-action/upload-sarif@v4    if: always()    with:      sarif_file: valca-results.sarif      category: valca

Or call it directly, without the action:

yaml

- run: pip install valca --quiet- run: valca scan . --no-color- run: valca scan . --format sarif > valca-results.sarif

- run: pip install valca --quiet- run: valca scan . --no-color- run: valca scan . --format sarif > valca-results.sarif

Findings appear as inline annotations on PR diffs, and in the repository's Security tab.

MCP server

The hook blocks an agent. The MCP server lets one ask.

There is no tool that edits, fixes or writes anything. A scanner that can modify code is a new attack surface, and it is the one VGL-MCP003 and VGL-MCP005 exist to catch.

Three limits are built in rather than configurable:

Scanning cannot leave the root. That root is the directory valca-mcp started in, or VALCA_MCP_ROOT if set. The agent picks the argument to scan, so without a boundary it could walk to ~/.ssh and map a filesystem it was never given.
Paths come back relative to that root. An absolute path carries your username and directory layout.
Matched source lines are never returned. For the secret rules that line is the secret.

Telemetry is off on this path whatever your configuration says. Your .valcarc is still honoured — disabled_rules, exclude_paths and min_severity all apply.

mcp is an optional extra, so installing Valca normally still pulls no runtime dependencies at all.

The hook remains the enforcement path. It runs on every write whether the model wants it or not; MCP is opt-in by the agent, and a check an agent can decline is not enforcement.

Development

bash

git clone https://github.com/PranLabs/valca.gitcd vigilpython3 -m venv venv && source venv/bin/activatepip install -e ".[dev]"pytest tests/ -v

git clone https://github.com/PranLabs/valca.gitcd vigilpython3 -m venv venv && source venv/bin/activatepip install -e ".[dev]"pytest tests/ -v

License

Business Source License 1.1 — free for non-commercial use. Commercial use requires a license agreement. Converts to MIT on 2030-06-26.

Feedback

Found a false positive? Want a rule that doesn't exist yet? Building with AI agents and hitting patterns Valca should catch?

Open an issue → github.com/PranLabs/valca/issues

Or: valca feedback

来源：README.md，提交 caad412

工具

工具元数据尚未被收录。

版本历史

v0.6.1最新Oct 7, 2026

Code	Meaning
`0`	No findings — write proceeds
`1`	Advisory findings only (MEDIUM / LOW / INFO)
`2`	CRITICAL or HIGH found — Claude Code blocks the write

Tool	Returns
`scan(path)`	Findings for a file or directory: rule, severity, message, file, line, suggested fix
`list_rules()`	The full catalogue — every rule id, severity, and what it catches

Rule	Severity	What it catches
VGL-DEP001	HIGH	Vulnerable Python packages (pip-audit)
VGL-DEP002	HIGH	Critical npm vulnerability (npm audit)
VGL-DEP003	HIGH	Vulnerable lockfile package (osv-scanner)

Valca

概览

安装

在 SourceWeft 中

其他 MCP 客户端

README

Valca

The Problem

Install

Network access

Usage

See It in Action

Rules

Secrets & Credential Exposure (14 rules)

GitHub Actions — AI Agent Surface (13 rules)

AI Agent — Prompt Injection (9 rules)

Dockerfile Hardening (8 rules)

Docker Compose (7 rules)

Terraform (7 rules)

Deserialization & Path Traversal (5 rules)

MCP Server Security (5 rules)

Web Application Security (5 rules)

AI Agent — Excessive Agency (4 rules)

Authentication & Session (4 rules)

Dependency Integrity (4 rules)

Kubernetes (4 rules)

Logging & Data Exposure (4 rules)

Swift / iOS (4 rules)

Dependency CVE Scanners (3 rules)

GitHub Actions — Workflow Hygiene (3 rules)

AI Agent — Configuration Files (2 rules)

JavaScript / TypeScript (2 rules)

Row-Level Security (2 rules)

Cross-Site Scripting (1 rule)

Cryptography (1 rule)

IAM Policies (1 rule)

Python (1 rule)

Shell Scripts (1 rule)

Trivy IaC Deep Scan (1 rule)

nginx (1 rule)

Configuration

Opt-out

Adding a Rule

GitHub Actions

MCP server

Development

License

Feedback

工具

版本历史

更多类似 Valca 的服务

Cowboy MCP

Hash Encoding Direct Credits

Ballmac