Add GitLab CI integration template #5

.gitlab-ci-isnad.yml

@@ -0,0 +1,49 @@
+# ISNAD Scanner GitLab CI Template
+# Docs: docs/gitlab-ci.md
+
+stages:
+  - test
+
+isnad_scan:
+  stage: test
+  image: node:20-alpine
+  variables:
+    # Scan target: file or glob pattern
+    ISNAD_SCAN_TARGET: "./**/*.js"
+    # Fail pipeline if risk level >= this value (critical|high|medium|low|none)
+    ISNAD_FAIL_THRESHOLD: "high"
+    # Incremental scan: only scan changes in merge requests
+    ISNAD_INCREMENTAL_SCAN: "true"
+    # Output SARIF report for GitLab Security Dashboard
+    ISNAD_OUTPUT_SARIF: "true"
+  script:
+    - npm install -g @isnad/scanner@latest
+    - |
+      if [ "$ISNAD_INCREMENTAL_SCAN" = "true" ] && [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
+        # Get list of changed files in MR
+        CHANGED_FILES=$(git diff --name-only origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...$CI_COMMIT_SHA | grep -E "\.(js|ts|py|sh|bash|php)$" | tr '\n' ' ')
+        if [ -z "$CHANGED_FILES" ]; then
+          echo "No relevant files changed, skipping scan"
+          exit 0
+        fi
+        SCAN_TARGET="$CHANGED_FILES"
+      else
+        SCAN_TARGET="$ISNAD_SCAN_TARGET"
+      fi
+    - |
+      if [ "$ISNAD_OUTPUT_SARIF" = "true" ]; then
+        isnad-scan batch $SCAN_TARGET --fail-threshold $ISNAD_FAIL_THRESHOLD --sarif > isnad-results.sarif
+      else
+        isnad-scan batch $SCAN_TARGET --fail-threshold $ISNAD_FAIL_THRESHOLD
+      fi
+  artifacts:
+    reports:
+      sarif: isnad-results.sarif
+    paths:
+      - isnad-results.sarif
+    when: always
+  rules:
+    - if: $ISNAD_SCAN_DISABLED
+      when: never
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

README_zh.md

@@ -0,0 +1,40 @@
+# $ISNAD
+
+**AI 代理的信任层**
+
+面向代理互联网的权益证明审计协议。审计员质押代币为代码安全背书，恶意代码会导致质押烧毁，干净代码则为审计员带来收益。
+
+## 问题背景
+
+AI 代理会从不可信来源安装技能，一个恶意技能就可能窃取凭证、泄露数据或者攻陷系统，目前没有标准化的信任评估方式。
+
+## 解决方案
+
+**权益证明审计：**
+- 审计员质押 $ISNAD 为技能背书
+- 如果发现恶意代码，质押将被烧毁
+- 干净的技能会为审计员带来收益
+- 用户在安装前可查看信任评分
+
+## 词源
+
+*Isnad* (إسناد) — 阿拉伯语意为「支持链」，是伊斯兰学术传统中通过追溯传播链来验证圣训真实性的机制，言论的可信度取决于其传播者的可信度。
+
+$ISNAD 将这一古老智慧应用到代码溯源场景中。
+
+## 文档
+
+- [白皮书](WHITEPAPER.md) — 完整协议规范
+
+## 项目状态
+
+🚧 **草案阶段** — 发布前正在收集反馈。
+
+## 相关链接
+
+- Moltbook: [moltbook.com/u/Rapi](https://moltbook.com/u/Rapi)
+- X: [@0xRapi](https://x.com/0xRapi)
+
+---
+
+*由 [Rapi](https://github.com/0xRapi) 构建 ⚡*

docs/gitlab-ci-example.yml

@@ -0,0 +1,42 @@
+# Example GitLab CI configuration with ISNAD Scanner
+include:
+  - remote: https://raw.githubusercontent.com/counterspec/isnad/main/.gitlab-ci-isnad.yml
+
+stages:
+  - build
+  - test
+  - deploy
+
+# Your existing build job
+build:
+  stage: build
+  image: node:20-alpine
+  script:
+    - npm install
+    - npm run build
+
+# ISNAD scan runs automatically in test stage (from included template)
+
+# Your existing test jobs
+unit_test:
+  stage: test
+  image: node:20-alpine
+  script:
+    - npm test
+
+# Your existing deploy job
+deploy:
+  stage: deploy
+  only:
+    - main
+  script:
+    - echo "Deploying to production"
+
+# Custom ISNAD configuration
+variables:
+  # Scan all JS/TS/PY files in src directory
+  ISNAD_SCAN_TARGET: "./src/**/*.{js,ts,py}"
+  # Fail only on critical severity findings
+  ISNAD_FAIL_THRESHOLD: "critical"
+  # Disable incremental scan, always scan all files
+  ISNAD_INCREMENTAL_SCAN: "false"

docs/gitlab-ci.md

@@ -0,0 +1,59 @@
+# GitLab CI Integration
+
+This document explains how to integrate ISNAD scanner into your GitLab CI/CD pipeline.
+
+## Quick Start
+
+Add the following to your `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - remote: https://raw.githubusercontent.com/counterspec/isnad/main/.gitlab-ci-isnad.yml
+```
+
+## Configuration
+
+You can customize the scan behavior by setting variables in your CI/CD settings or in your `.gitlab-ci.yml`:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ISNAD_SCAN_TARGET` | File or glob pattern to scan | `"./**/*.js"` |
+| `ISNAD_FAIL_THRESHOLD` | Fail pipeline if risk level >= this value: `critical` / `high` / `medium` / `low` / `none` | `"high"` |
+| `ISNAD_INCREMENTAL_SCAN` | Only scan changed files in merge requests | `"true"` |
+| `ISNAD_OUTPUT_SARIF` | Output SARIF report for GitLab Security Dashboard | `"true"` |
+| `ISNAD_SCAN_DISABLED` | Set to `true` to disable ISNAD scan | `false` |
+
+## Example Configuration
+
+```yaml
+include:
+  - remote: https://raw.githubusercontent.com/counterspec/isnad/main/.gitlab-ci-isnad.yml
+
+variables:
+  ISNAD_SCAN_TARGET: "./src/**/*.{js,ts,py}"
+  ISNAD_FAIL_THRESHOLD: "medium"
+```
+
+## How It Works
+
+1. **Full scan on default branch**: Every commit to your main branch will trigger a full scan of all target files
+2. **Incremental scan on MRs**: Merge requests only scan changed files to speed up pipelines
+3. **SARIF integration**: Scan results are automatically sent to the GitLab Security Dashboard
+4. **Pipeline failure**: If any finding meets or exceeds the fail threshold, the pipeline will fail
+
+## Security Dashboard
+
+To view scan results in the GitLab Security Dashboard:
+1. Go to your project page
+2. Click "Security & Compliance" → "Security Dashboard"
+3. Filter by "Tool: ISNAD Scanner" to see all findings
+
+## Troubleshooting
+
+### Scan is running but no findings are showing up
+- Ensure your `ISNAD_SCAN_TARGET` pattern matches the files you want to scan
+- Check that the files have supported extensions (js, ts, py, sh, bash, php)
+
+### Pipeline is failing on legitimate code
+- Adjust `ISNAD_FAIL_THRESHOLD` to a higher severity level
+- You can also add false positive exceptions by adding `// isnad-ignore` comment above the line

docs/what-is-isnad_zh.md

@@ -0,0 +1,99 @@
+# 什么是 ISNAD？
+
+ISNAD (إسناد) 是一个权益证明认证协议，为 AI 资源创建信任层。名称来源于伊斯兰学术传统中的 *isnad* —— 用于验证圣训真实性的传播链，言论的可信度仅取决于其传播者链的可信度。
+
+## 问题背景
+
+AI 代理越来越依赖来自不可信来源的共享资源：
+- **技能** — 可执行代码包、工具、API 集成
+- **配置** — 代理配置、网关设置
+- **提示词** — 系统提示词、人设、行为指令
+- **记忆** — 知识库、RAG 文档
+- **模型** — 微调模型、LoRA、适配器
+
+单个被篡改的资源可能会：
+- 泄露凭证和敏感数据
+- 执行未授权命令
+- 操纵代理行为
+- 攻陷整个系统
+
+现有方案无法规模化：
+- **人工代码审查** — 大多数代理无法进行审计
+- **集中审批** — 单点故障、流程瓶颈
+- **声誉评分** — 可被操纵，新作者无法从零开始积累
+- **沙箱隔离** — 不完整，很多资源需要真实权限才能运行
+
+## 解决方案
+
+ISNAD 通过经济激励创建市场定价的信任信号：
+
+1. **资源被铭刻** 在 Base L2 上，包含内容和元数据
+2. **审计员质押 $ISNAD 代币** 为资源安全性背书
+3. **质押被锁定** 一段时间（7-90天）
+4. **如果资源是恶意的**，陪审团会进行审查，质押将被罚没（烧毁）
+5. **如果资源是安全的**，审计员从奖励池获得收益
+
+### 方案优势
+
+- **利益绑定** — 审计员承担真实风险，虚假认证会导致代币烧毁
+- **专业能力自筛选** — 只有有信心的审计员才会质押，市场会自动筛选出合格的审计能力
+- **永久可验证** — 所有内容都在链上，无需信任外部基础设施
+- **抗攻击** — 女巫攻击需要大量资本，合谋会导致所有合谋者的质押被烧毁
+
+## 链上铭刻
+
+与需要固定服务的 IPFS 方案不同，ISNAD 直接将资源铭刻在 Base L2 的调用数据中：
+
+- **每 KB 铭刻成本约 0.01 美元**
+- **永久** 链上存储
+- **零** 外部依赖
+
+资源使用 SHA-256 哈希进行内容寻址，确保随时可以进行完整性校验。
+
+## 核心概念
+
+### 信任评分
+资源上的总加权质押额。质押额越高 = 经济背书越多 = 信任度越高。
+
+### 信任等级
+基于信任评分的分类：
+- **未验证** — 没有认证
+- **社区级** — 质押额 ≥100 $ISNAD
+- **已验证** — 质押额 ≥1,000 $ISNAD
+- **可信任** — 质押额 ≥10,000 $ISNAD
+
+### 认证
+当审计员为某个资源质押时，会创建一个包含以下内容的认证记录：
+- 质押金额
+- 锁定期限
+- 资源哈希
+- 审计员地址
+
+### 罚没
+如果发现资源是恶意的：
+1. 任何人都可以标记它（需要 100 $ISNAD 保证金）
+2. 随机选择 5 名审计员组成陪审团
+3. 陪审团投票（需要 67% 绝对多数同意）
+4. 如果判定为有罪：该资源上的所有质押都被烧毁
+5. 标记者将收回保证金并获得奖励
+
+## 协议架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      ISNAD 协议                              │
+├──────────────┬──────────────┬──────────────┬───────────────┤
+│  ISNADToken  │ ISNADRegistry│ ISNADStaking │  ISNADOracle  │
+│  (ERC20 +    │  (资源铭刻   │  (质押 +     │  (标记 +       │
+│   投票)      │   + 元数据)  │   认证)      │   陪审团)       │
+├──────────────┴──────────────┴──────────────┴───────────────┤
+│  ISNADRewardPool        │        ISNADGovernor             │
+│  (收益分配)             │        (DAO + 时间锁)             │
+└─────────────────────────┴──────────────────────────────────┘
+```
+
+## 下一步
+
+- [成为审计员](./auditors.md) — 开始质押并赚取收益
+- [质押指南](./staking.md) — 分步操作说明
+- [集成指南](./integration.md) — 为你的代理添加信任检查