Skip to content
Back to search

semia

MarketplaceWorks with Claude CodeGitHub

Semia, security audit for AI agent skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/berabuddies-semia/badge.svg)](/listings/berabuddies-semia)

HTML

<a href="/listings/berabuddies-semia"><img src="/api/listings/berabuddies-semia/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`semia scan` needs an LLM for the **synthesize** step (the other three stages are deterministic, no key required). If you run Semia via a host plugin (Codex / Claude Code / OpenClaw) skip this — the host agent already does synthesize for you.

Four providers are supported. Pick one and export its credentials:

# OpenAI Responses API — default; also works for DeepSeek / OpenRouter / vLLM
export OPENAI_API_KEY=sk-...
# optional: export OPENAI_BASE_URL=https://api.deepseek.com/v1

# Anthropic Messages API
export SEMIA_LLM_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
# optional: export ANTHROPIC_BASE_URL=https://api.anthropic.com

# Locally-installed Claude Code CLI (uses your Claude Code login)
export SEMIA_LLM_PROVIDER=claude

# Locally-installed Codex CLI (uses your Codex login)
export SEMIA_LLM_PROVIDER=codex

Override the model with `--model <name>` on any `semia scan` invocation, or persist it via `SEMIA_LLM_MODEL`. Models are free-form strings — anything the endpoint accepts (`gpt-5.5`, `deepseek-v4`, `claude-opus-4-7`, …).

See [Configuration](ADVANCED_USAGE.md#configuration) for the full provider matrix, base-URL support, timeout/retry knobs, and synthesis-loop tuning.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "semia",
  3. "owner": {
  4. "name": "berabuddies",
  5. "url": "https://github.com/berabuddies"
  6. },
  7. "plugins": [
  8. {
  9. "name": "semia",
  10. "source": "./packages/semia-plugins/claude-code",
  11. "description": "Static security audit toolkit for AI agent skills — surfaces every capability a skill may exercise, with evidence.",
  12. "homepage": "https://github.com/berabuddies/Semia",
  13. "category": "Developer Tools",
  14. "author": {
  15. "name": "berabuddies",
  16. "url": "https://github.com/berabuddies"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 244 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Semia
  2. > **Security audit for AI agent skills.** Know what a skill *can* do
  3. > before you trust it.
  4. [![CI](https://github.com/berabuddies/Semia/actions/workflows/ci.yml/badge.svg)](https://github.com/berabuddies/Semia/actions/workflows/ci.yml)
  5. [![Lint](https://github.com/berabuddies/Semia/actions/workflows/lint.yml/badge.svg)](https://github.com/berabuddies/Semia/actions/workflows/lint.yml)
  6. [![codecov](https://codecov.io/gh/berabuddies/Semia/graph/badge.svg)](https://codecov.io/gh/berabuddies/Semia)
  7. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
  8. [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
  9. Agent skills are markdown files with embedded shell commands, network calls,
  10. and tool invocations. They run with **your credentials, on your machine,
  11. with your data**. Semia reads a skill as data — never executes it — and
  12. produces an evidence-backed report of every capability it may exercise.
  13. It is the difference between
  14. > *"I trust this skill because the README looks fine."*
  15. and
  16. > *"I trust this skill because Semia extracted 14 actions, 6 effects,
  17. > and 2 secret reads — and every one is grounded in a specific source line."*
  18. ---
  19. ## Quick example
  20. Pick whichever fits how you already work.
  21. ### As a CLI
  22. ```bash
  23. pip install semia-audit
  24. semia scan ./some-skill
  25. ```
  26. `scan` does prepare → synthesize (via your configured LLM provider) →
  27. detect → report in one shot. Output lands under
  28. `.semia/runs/<skill-slug>/` by default — pass `--out <path>` to override.
  29. You'll need an LLM provider configured first — see
  30. [Set up an LLM provider](#set-up-an-llm-provider) below.
  31. ### Inside Codex, Claude Code, or OpenClaw
  32. Install the plugin once. Each host has its own flow.
  33. **Codex** — pick either path:
  34. *Shell (scripts and CI):*
  35. ```bash
  36. codex plugin marketplace add berabuddies/Semia
  37. ```
  38. Then enable the plugin by appending to `~/.codex/config.toml`:
  39. ```toml
  40. [plugins."semia@semia"]
  41. enabled = true
  42. ```
  43. *Interactive plugin manager inside the Codex CLI:*
  44. 1. Launch `codex`.
  45. 2. Inside Codex, input `/plugins` (plural — opens the plugin panel).
  46. 3. Press **←** (Left) to enter **Add marketplace**.
  47. 4. Enter `berabuddies/Semia`.
  48. 5. Back in the plugin panel, toggle `semia` on from the
  49. newly-added marketplace.
  50. **Claude Code** — pick either path:
  51. *Shell (one-liner):*
  52. ```bash
  53. claude plugin marketplace add berabuddies/Semia
  54. claude plugin install semia@semia
  55. ```
  56. *Interactive plugin manager inside the Claude Code CLI:*
  57. 1. Launch `claude`.
  58. 2. Inside Claude Code, input `/plugins` (plural — opens the plugin panel).
  59. 3. Press **→** (Right) twice and select **Add Marketplace**.
  60. 4. Enter `berabuddies/Semia`.
  61. Either path registers the marketplace; finish installing `semia` from
  62. the panel or with `claude plugin install semia@semia`.
  63. **OpenClaw** — one shell command registers the marketplace and installs:
  64. ```bash
  65. openclaw plugins install clawhub:semia
  66. ```
  67. Then in any chat with the host agent just ask:
  68. > Run Semia audit on ./some-skill
  69. The host agent itself acts as the synthesize step — **no API key needed**.
  70. The bundled `semia.pyz` handles prepare / detect / report deterministically.
  71. ### Fix what Semia finds
  72. ```bash
  73. semia repair .semia/runs/some-skill --from-scan
  74. ```
  75. `repair` reads the findings and synthesized facts from an existing scan,
  76. traces each violation back through the Datalog rules to identify the root
  77. cause, then calls an LLM to generate a SKILL.md patch — either fixing
  78. the problematic content directly or adding specific security constraints.
  79. ```bash
  80. # Or scan + repair in one shot:
  81. semia repair ./some-skill
  82. ```
  83. ### Outputs
  84. You get `report.md` — findings ranked by severity, every one tied to a
  85. specific source line. Need [SARIF 2.1.0](https://sarifweb.azurewebsites.net/)
  86. for GitHub Code Scanning, or structured JSON for downstream tooling? One
  87. more command:
  88. ```bash
  89. semia report .semia/runs/some-skill --format sarif # for GitHub Code Scanning
  90. semia report .semia/runs/some-skill --format json # structured payload
  91. ```
  92. ## Set up an LLM provider
  93. `semia scan` needs an LLM for the **synthesize** step (the other three
  94. stages are deterministic, no key required). If you run Semia via a host
  95. plugin (Codex / Claude Code / OpenClaw) skip this — the host agent already
  96. does synthesize for you.
  97. Four providers are supported. Pick one and export its credentials:
  98. ```bash
  99. # OpenAI Responses API — default; also works for DeepSeek / OpenRouter / vLLM
  100. export OPENAI_API_KEY=sk-...
  101. # optional: export OPENAI_BASE_URL=https://api.deepseek.com/v1
  102. # Anthropic Messages API
  103. export SEMIA_LLM_PROVIDER=anthropic
  104. export ANTHROPIC_API_KEY=sk-ant-...
  105. # optional: export ANTHROPIC_BASE_URL=https://api.anthropic.com
  106. # Locally-installed Claude Code CLI (uses your Claude Code login)
  107. export SEMIA_LLM_PROVIDER=claude
  108. # Locally-installed Codex CLI (uses your Codex login)
  109. export SEMIA_LLM_PROVIDER=codex
  110. ```
  111. Override the model with `--model <name>` on any `semia scan` invocation, or
  112. persist it via `SEMIA_LLM_MODEL`. Models are free-form strings — anything
  113. the endpoint accepts (`gpt-5.5`, `deepseek-v4`, `claude-opus-4-7`, …).
  114. See [Configuration](ADVANCED_USAGE.md#configuration) for the full provider
  115. matrix, base-URL support, timeout/retry knobs, and synthesis-loop tuning.
  116. ## What you get
  117. A run writes everything under `.semia/runs/<run-id>/`. **Most users only
  118. ever open the reports**:
  119. | Report | When |
  120. | ------------------- | --------------------------------------------------------- |
  121. | `report.md` | always produced by `semia scan` — read this first |
  122. | `report.sarif.json` | on demand via `semia report --format sarif` — feed to GitHub Code Scanning |
  123. | `report.json` | on demand via `semia report --format json` — structured payload (check + evidence + detector) for programmatic consumers |
  124. Because every finding traces back to a source line, the SARIF drops cleanly
  125. into GitHub Code Scanning and reviewers see annotations directly on the
  126. skill PR.
  127. <details>
  128. <summary>Other artifacts in the run directory (internal — for tooling, debugging, or re-querying)</summary>
  129. | Artifact | Purpose |
  130. | ------------------------- | -------------------------------------------------- |
  131. | `synthesized_facts.dl` | the behavior map (Datalog facts) — re-queryable |
  132. | `detection_findings.dl` | findings derived by rule evaluation |
  133. | `prepared_skill.md` | normalized skill text with stable line anchors |
  134. | `prepare_units.json` | reference units the evidence text aligns against |
  135. | `synthesis_metadata.json` | provider, model, retries, score, stop reason |
  136. | `run_manifest.json` | end-to-end manifest of the run |
  137. | `repair_result.json` | repair outcomes (when `semia repair` is run) |
  138. | `patched/SKILL.md` | the repaired SKILL.md (when `semia repair` is run) |
  139. </details>
  140. ## More docs
  141. - [Advanced usage](ADVANCED_USAGE.md) covers the worked example, trust
  142. model, installation, configuration, and common workflows.
  143. - [Development](DEVELOPMENT.md) covers the repository layout and local
  144. development workflow.
  145. ## Project background
  146. The technique behind Semia is described in the Semia paper
  147. ([arXiv:2605.00314](https://arxiv.org/abs/2605.00314) ·
  148. [PDF](https://arxiv.org/pdf/2605.00314)). Semia is the
  149. **deterministic acceptance boundary** around behavior mapping: agents may
  150. extract facts, but only checked, evidence-grounded facts make it into a
  151. report.
  152. ## Security
  153. To report a security vulnerability, see [SECURITY.md](SECURITY.md). Please
  154. do **not** file public GitHub issues for security problems.
  155. ## Contributing
  156. Contributions are welcome — bug reports, documentation fixes, detector
  157. rules, and code. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow
  158. and the DCO sign-off requirement.
  159. ## License
  160. Semia is released under the [Apache License 2.0](LICENSE).
  161. Copyright 2026 RiemaLabs.
  162. ## Citation
  163. If you use this tool, please cite our paper:
  164. ```bibtex
  165. @misc{wen2026semia,
  166. title = {Semia: Auditing Agent Skills via Constraint-Guided Representation Synthesis},
  167. author = {Wen, Hongbo and Li, Ying and Liu, Hanzhi and Shou, Chaofan and Chen, Yanju and Tian, Yuan and Feng, Yu},
  168. year = {2026},
  169. eprint = {2605.00314},
  170. archivePrefix = {arXiv},
  171. primaryClass = {cs.CR},
  172. doi = {10.48550/arXiv.2605.00314},
  173. url = {https://arxiv.org/abs/2605.00314}
  174. }
  175. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.