linmas - Proof-carrying defensive security reviews for AI-a

项目说明

<di="center">
<img src=" alt="Linmas logo" width="180" height="180">

<h1>Linmas Proof Review</h1>

<p><strong>Proof-carrying defensi reviews for AI-assisted software.</strong></p>

<p>Turn one explicit change into a normalized finding, deterministic policy decision, and portable Review Capsule—with human review always required.</p>

<p>
<a href=" alt="CI" src="
<a href=" alt="npm 0.9.1" src="
<a href=" alt="npm total downloads" src="
<a href=" alt="npm weekly downloads" src="
<a href=" alt="release v0.9.1" src="
<a href="LICENSE"><img alt="License: Apache-2.0" src="
<img alt="Node.js 24+" src="
<a href=" alt="Codex primary" src="
<a href="#ai-agent-compatibility"><img alt="Claude Code compatible" src="
<a href="#ai-agent-compatibility"><img alt="Hermes Agent format only" src="
<a href="#ai-agent-compatibility"><img alt="AI agent skills portable" src="
<img alt="Security: defensive only" src="
</p>
</div>

Current release: v0.9.1

Linmas 0.9.1 is a documentation and branding follow-up to the 0.9.0 release. It updates the npm README, badges, and logo without changing runtime behavior. The 0.9.0 release introduced:

Install the published CLI with Node.js 24 or newer:

See the 0.9.1 release notes and the full 0.9.0 release and upgrade guidance. Existing 0.8.0 users do not need a data migration.

Try it in 60 seconds

From a clone of this repository, with Node.js 24 or newer:

The default offline demo is an OFFLINE FIXTURE REPLAY — NO MODEL CALL. It needs no provider credentials and makes no network call. It a synthetic SQL-injection change, replays a checked-in normalized result, e the baseline-appsec policy, and the generated capsule in memory.

Example output:

This is a reproducible demonstration of the review pipeline, not a claim that a model was called during offline replay.

OpenAI Build Week 2026 — historical participation

Linmas was pre included in the OpenAI Build Week 2026 hackathon. That participation has ended: this repository is not an acti submission, and e instructions are no longer part of the current project guidance.

The dated Build Week implementation and reproducibility record remains a as historical context. The archi examples can still be run as a normal offline demonstration:

The checked-in sample is examples/build-week/insecure-query.diff. Both commands above use synthetic, offline fixtures and make no model call. The separate li path is opt-in and sends only the explicitly named input after confirmation.

Key engineering decisions were deliberate:

| Decision | Reason |
|---|---|
| Keep the default offline demo path | The demo is deterministic, needs no credentials or network dependency, and clearly says that no model was called. |
| Separate li behind --li | Review content cannot leave the machine through the demo without explicit intent. |
| model output before policy or e creation | Malformed provider output cannot bypass the Linmas result contract. |
| Bind capsules to exact input bytes with SHA-256 | Review e stays tied to the input that was actually e. |
| Require human review for every result | A model finding, policy pass, or valid proof bundle is e, ne approval or certification. |

See the historical Build Week implementation and reproducibility record for the dated baseline, feature commits, li, architecture, commands, and limitations. Current installation options and supported platforms are summarized below and in the usage guide.

Documentation

Choose the guide that matches your language and installation goal:

GitHub's standard repository na exposes fixed tabs; these public usage guides are tracked at the repository root and linked here for reliable discovery. The guides are intentionally excluded from the npm package.

AI agent compatibility

Linmas remains Codex-first as a nati while staying portable across AI coding agents. Codex was also the primary integration used in the historical OpenAI Build Week 2026 project. The compatibility e policy defines the limits of current claims. Installation detection is not runtime conformance; compatibility with other agents depends on the integration le.

0.9.1 is a documentation-only follow-up to the 0.9.0 feature release. Its content identity is re; release artifact hashes and pro bind the bytes actually published. A prior accepted SHA does not automatically qualify later source changes. Neither the identity file, offline fixtures, nor publication establishes live host or model behavior.

| AI agent or surface | Status | Supported integration |
| --- | --- | --- |
| Codex | Primary / native | Git marketplace plugin, ele, se MCP tools, managed skill directory, and pro review. |
| Claude Code | Managed installation adapter | Managed installation of ele. Claude API pro review is a separate integration; it does not Claude Code runtime behavior. |
| Hermes Agent | Partial / format-level only | Linmas SKILL.md content is a candidate for Hermes manual loading. Actual Linmas execution, MCP registration, and safety enforcement are UNKNOWN until separately tested. |
| Gemini CLI and other coding agents | Portable / manual | The Markdown skill instructions can be imported or adapted where the agent supports equi instructions. Linmas does not yet provide a Gemini-specific installer, provider adapter, or MCP registration. |

“Portable / manual” means the defensi can be reused; it does not mean nati has been . New nati must ha detection, install/uninstall tests, safety-boundary parity, and a maintenance owner before Linmas labels them .

Why the name “Linmas”?

Linmas stands for Perlindungan Masyarakat—an Indonesian phrase for community protection. The name reflects the idea that useful protection should be close to the people doing the work, a before a problem becomes an incident, and understandable enough to support better human decisions.

That idea matters for AI-assisted software. Solo de, indie hackers, vibe coders, maintainers, and engineering teams can ship quickly without always having a dedicated security specialist nearby. Linmas gives them a practical first checkpoint: focused security skills, a bounded review workflow, deterministic policy, and portable e that can be inspected rather than blindly trusted.

Linmas is not the “police”, “military”, or final authority of application security. It is intended to be the first layer of defense closest to e builders—helping people notice risks earlier, ask better questions, and bring stronger e to the humans responsible for the final decision.

This open-source project is independently de. It is not affiliated with any go institution, and its name does not imply go authority, certification, or endorsement. It is also not endorsed by OpenAI.

Who Linmas is for

Run a li review

If Codex is already usable on the machine, run a synthetic case live:

Without --model, Linmas uses the single default reported by the current Codex account and fails closed if selection is ambiguous. For an explicit model selection:

The live demo is intentionally opt-in. --yes acknowledges that the named input leaves the machine. To preserve an atomic e artifact:

Or review your own explicit input:

On 2026-07-18, one authorized synthetic run was with Codex CLI 0.144.5, ChatGPT subscription authentication, and the account- gpt-5.6-sol model. It returned a schema-valid high-se SQL-injection finding and a blocked policy decision. This is e for that tested configuration, not a guarantee that the model is a to every account.

The Review Capsule

A Review Capsule is a JSON e object that connects:

Capsules are written with destination preflight and atomic no-o behavior. They deliberately exclude raw provider responses, credentials, email addresses, session identifiers, and request identifiers.

A capsule is not a digital signature, remote attestation, certification, or proof that software is secure. It is a re e en for a bounded run.

The Proof Chain

Turn a Review Capsule or a completed Codex Security sealed scan into a portable, human-re e bundle:

The creation wizard records a disposition and rationale for every finding, derives an o disposition, and writes decision-receipt.json, report.md, report.html, and hashed source e. The bundle is immutable at the destination and can be offline without provider credentials or network access.

Codex Security imports require the complete sealed scan directory containing scan-manifest.json, findings.json, and co.json. Linmas the manifest references and artifact hashes before importing the three structured files. It does not copy the full scan, execute scan content, or accept a findings-only file as a source.

SSH signing is optional. A valid signature pro and key possession; identity becomes trusted only when the supplies a matching --allowed-signers file:

Proof bundles are e summaries, not approvals, certifications, or proof that software is secure. Human review remains required.

Compare before and after

Compare two capsules locally, without a provider or network call:

The comparison both complete capsules, then reports added, resolved, persistent, and changed findings plus the policy transition. It does not claim that an empty delta pro.

Deterministic policy, ne approval

Apply a built-in declarati after normalization:

Built-in packs are baseline-appsec, cloud-change, and release-security. Local policy files are bounded, schema- JSON with no commands, code, expressions, templates, plugins, remote imports, or provider hooks.

Decisions are pass, needs-review, or blocked. A policy pass does not prove the change is secure, compliant, certified, or approved. Safety failures fail closed, and human review is required for every result.

Authentication and privacy boundaries

Linmas is subscription-first for Codex. It supports accounts whose Codex installation reports either:

Linmas does not log you in, ask for an OpenAI API key, or store credentials. Codex owns authentication. Linmas uses the Codex app-ser surface to classify the current auth mode and list account- models, then the explicitly selected model before li.

Prepare mode reads only the named input file or explicit stdin, ne Git, ne the repository, and makes no network call:

For compatibility, the legacy alias also resolves:

Native MCP tools accept both the namespaced specialist ID and this legacy alias, then normalize both to the same specialist contract. Invalid MCP requests return schema- errors with safe field/reason metadata. Provider failures use granular codes such as PROING, PRO, and PRO; credentials, review input, raw stderr, and provider responses are ne.

Li is separately enabled and confirms that data leaves the machine. Linmas constructs the request from the named input and runs Codex in a managed temporary working directory with a read-only sandbox request, approvals disabled, an ephemeral session, and user config and repository rules ignored.

Those controls reduce ambient influence, but this does not guarantee that Codex cannot read other filesystem paths permitted by the host and Codex sandbox.

Linmas makes no claim of filesystem isolation to the named input. Use li only with content you are authorized to transmit.

Linmas-branded security skills

Every public skill is namespaced for disco and attribution:

| Skill | Focus |
|---|---|
| linmas-secure-code-re | Application security findings, threat modeling, and remediation. |
| linmas-smart-contract-re | Authorized smart-contract and protocol risk review. |
| linmas-cloud-hardening-architect | IAM, segmentation, workload, and platform hardening. |
| linmas-controls-compliance-re | Control mapping, e, and audit-readiness gaps. |
| linmas-incident-triage-lead | Classification, containment planning, and e preser. |
| linmas-exploit- | Bounded proof-of-impact in authorized en. |
| linmas-secure-systems-architect | Trust zones, identity, and secure system design. |
| linmas-security-domain-router | Route a request to the appropriate Linmas specialist. |
| linmas-security-operations-lead | Monitoring, escalation, and operational hardening. |
| linmas-detection-rules-engineer | SIEM logic, telemetry mapping, tuning, and false-positi. |
| linmas-threat-research-analyst | IOC analysis and intelligence-to-detection translation. |

Legacy unprefixed names remain aliases for migration, but new documentation and installations use canonical linmas-* identities.

Installation hosts and execution pro

Installation hosts and execution pro are independent:

| Capability | Supported surface |
|---|---|
| Installation hosts | Claude Code and Codex managed skill directories |
| Execution pro | Claude and Codex pro configuration |

Credentials are ne in an installation manifest. Li is opt-in. Gemini and other agents are not registered installation hosts or execution pro in 0.9.1. Additional installation hosts remain demand-driven and require testable install/uninstall behavior, safety-boundary parity, and a maintenance owner.

Security advisor skills

The skill files remain useful directly inside compatible coding agents. Each specialist defines an advisor review mode, a design review mode, and a stable finding :

linmas-security-domain-router selects a specialist while preserving scope and authorization. Optional repository policy can shape agent behavior, but it does not automatically filter every agent response. Human review is required.

Secure code advisor review

linmas-secure-code-re emphasizes affected surface, preconditions, impact, remediation, and . Its deterministic checks are recommendations that run only when invoked. Optional repository policy can strengthen local review con but does not automatically filter every agent response or replace human review.

Historical Build Week implementation notes

| Before the Build Week implementation | Linmas Proof Review |
|---|---|
| A collection of defensi instructions | A bounded review workflow plus branded installable skills |
| Provider output without portable e | Strict normalized result and exact-input Review Capsule |
| Pro credential assumptions | Codex-nati subscription or Codex-managed API key discovery |
| Indi review result | Deterministic policy and offline before/after comparison |
| Manual product walkthrough | 60-second offline demo plus explicit live path |

Codex contributed as the pro review engine, implementation collaborator, and surface. Humans chose the scope, authorization boundaries, model, policy thresholds, safety contract, privacy language, publication scope, and final commits. See the historical Build Week e for the history and reproduction commands.

Platform and runtime

Native MCP plugin

Install the public Git marketplace and the Linmas plugin:

Important: marketplace is per device

This is a public GitHub repository marketplace, not yet an entry in the global Codex/ChatGPT Plugins Directory. Therefore, Linmas will not automatically appear in search on another computer just because you are signed in to the same ChatGPT account. Add the marketplace once on each computer:

After installation, restart Codex completely and create a new task. If linmas is still not listed, that the computer has Git, Node.js 24+, and network access to GitHub. The official Plugins Directory is a separate publication channel that requires OpenAI submission, review, and approval; GitHub and npm publication do not automatically add Linmas to that global catalog.

To pin an immutable release instead of following main, replace --ref main with --ref v0.9.1. After installation or upgrade, restart the Codex desktop/app-server and start a fresh task. A stale app-server can retain an MCP child process from an older or deleted plugin cache.

To refresh an existing marketplace installation that follows a moving ref such
as main, run:

marketplace upgrade refreshes the configured ref; it does not change an
immutable v0.8.0 ref, and a second marketplace add with --ref v0.9.1 is
rejected while the old source is registered. To move a pinned installation from
v0.8.0 to v0.9.1, remove the installed plugin and old marketplace, re-add it
with --ref v0.9.1, install the plugin again, and the configured ref and
installed . See the 0.9.0 upgrade guidance.
Always restart Codex and start a fresh task after .

The public marketplace tracks a ready-to-install plugin at plugins/linmas. Maintainers regenerate it from canonical sources and every file byte-for-byte:

Npm users can also build an independent local plugin directory:

The builder copies exactly ele Linmas skills, the bounded MCP server, policy/runtime files, .mcp.json, and the package metadata required to report the canonical . It does not mutate a user's marketplace configuration. De cachebusters are host-artifact metadata and are not part of the canonical source or package .

The MCP ser exactly se:

| Tool | Boundary |
|---|---|
| linmas_re | Interactive or text-fallback human disposition after findings are a; never an approval. |
| linmas_re | Offline preparation; no provider and no writes. |
| linmas_re | Offline capsule comparison. |
| linmas_policy_e | Offline deterministic policy e. |
| linmas_proof_ | Offline proof-bundle . |
| linmas_proof_create | Local write only after confirm_write=true. |
| linmas_re | Provider transmission only after confirm_transmission=true; returns the bound reference needed by linmas_re. |

Tool results expose bounded status such as prepared, , and executed, plus humanRe=true; every result remains needs_human_review. A prepared result does not call a provider or write output. Offline tools do not transmit data. A pro review transmits only after explicit consent, and a proof bundle is written only after explicit write confirmation. Timeouts cancel provider work and prevent late normalization, policy e, capsule creation, or final output writes.

After linmas_re returns, pass re.handle as re and re.capsuleDigest as capsule_digest to linmas_re. Do not send a caller-supplied re; the decision flow uses the bound process-local reference and exact digest.

Interacti gate

When a re has produced findings, linmas_re requests an explicit disposition through MCP form elicitation when the host supports it. The first form offers:

If no findings are actionable, A is omitted. If the host cannot show an MCP form, Linmas returns the same choices as a structured chat fallback and does not choose one automatically. A generic “lanjutkan” is not sufficient disposition. The gate uses the MCP protocol's client-side form elicitation; host permission modes remain separate controls.

Codex and Claude Code must have the Linmas MCP ser for the form to appear. A Full Access or --dangerously-skip-permissions mode controls command permission prompts; it does not grant a Linmas review disposition. If the active host suppresses or lacks MCP elicitation, the structured chat fallback remains mandatory.

Command reference

| Command | Purpose |
|---|---|
| linmas list | List canonical Linmas skills. |
| linmas detect | Detect supported installation hosts. |
| linmas onboard | Inspect host and Codex account capabilities. |
| linmas doctor | Diagnose managed installations and duplicates. |
| linmas install <skill> | Install one canonical skill; add --dry-run to preflight. |
| linmas uninstall <skill> | Remove a Linmas-managed skill on supported POSIX filesystems; Windows fails closed before mutation. |
| linmas review ... | Prepare locally or execute an explicit provider review. |
| linmas review compare before.json after.json | Compare two capsules offline. |
| linmas proof create <source> --bundle <dir> | Record human decisions and create a portable proof bundle. |
| linmas proof <dir> | bundle hashes and optional SSH signature offline. |
| npm run demo:judge | Run the deterministic offline demo. |
| npm run demo:proof | Create and an ephemeral offline Proof Chain bundle. |
| npm run | package structure, skills, examples, and secrets. |
| npm run e | Run checked-in e cases without model calls. |
| npm run co | Run tests with enforced source co thresholds. |

Limitations and safety

Contributing, security, and license

Contributions are welcome through CONTRIBUTING.md. Report according to the security policy. Community conduct is go by the Code of Conduct.

Linmas is licensed under Apache-2.0. See NOTICE and TRADEMARK.md for attribution and name-use guidance. Linmas is inspired by Indonesia's community-protection concept, *Perlindungan Masyarakat*, and is not affiliated with a go institution or endorsed by OpenAI.

项目信息

开发语言：JavaScript

Star 数：2

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Proof-carrying defensive security reviews for AI-assisted software, with deterministic policy, portable evidence, and human review required.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。