# ldesign-security

**Repository Path**: ldesign-v1/ldesign-security

## Basic Information

- **Project Name**: ldesign-security
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @composy/security

`@composy/security`
是一个面向 Node.js/TypeScript 项目的企业级安全工具包，覆盖依赖漏洞扫描、代码审计、敏感信息检测、注入分析、许可证合规、供应链分析、SBOM 生成、持续监控、Git 平台集成与多格式报告输出。它既可以作为 CLI 直接接入本地开发和 CI/CD，也可以作为库嵌入到自定义安全流程中。

English documentation: [`README.en.md`](./README.en.md)

## 功能概览

- 综合扫描：`SecurityScanner` 统一编排漏洞、代码、依赖、敏感信息、注入、许可证与供应链检查。
- 漏洞检测：结合 `npm audit` 与 OSV，并优先读取 `node_modules` 中真实安装版本提升准确度。
- 代码安全：支持代码审计、注入检测、加密使用分析、API 安全检查、容器与网络扫描。
- 合规能力：内置许可证合规检查、常见标准映射（OWASP / PCI DSS / GDPR / SOC2 / ISO27001）。
- 报告输出：支持 HTML、JSON、YAML、Markdown、PDF、Excel/CSV、SARIF 与扫描历史对比报告。
- 自动化：支持通知、调度、持续监控、Git Hook、PR/MR 评论和 Issue 创建。
- 可扩展：`SecurityScanner` 支持 `customTasks`，业务侧规则可以直接接入统一摘要与报告。
- 工程集成：完整 TypeScript 类型、ESM/CJS/d.ts 产物、CLI 入口和稳定的公共导出面。

## 安装

```bash
pnpm add -D @composy/security
```

也可以通过统一 CLI 接入：

```bash
pnpm add -D @composy/cli @composy/security
ldesign security --help
```

## 快速开始

### 1. 直接使用 CLI

```bash
# 执行完整安全扫描
npx lsec scan --severity medium --max-concurrency 4

# 生成多种格式报告
npx lsec report --format html,json,sarif --exclude "dist/**,coverage/**"

# 在 CI 中按严重程度控制退出码
npx lsec ci --fail-on high --sarif --sarif-output security-results.sarif --json
```

### 2. 作为库嵌入

```ts
import { SecurityScanner } from '@composy/security'

const scanner = new SecurityScanner({
  projectDir: process.cwd(),
  exclude: ['dist/**', 'coverage/**'],
  severity: 'medium',
  includePerformance: true,
  maxConcurrency: 4,
  customTasks: [
    {
      id: 'workspace-policy',
      title: 'Workspace policy',
      async run() {
        return []
      },
    },
  ],
})

const result = await scanner.scan()

console.log('风险等级:', result.riskLevel)
console.log('问题摘要:', result.summary)
console.log('扫描元数据:', result.metadata)
```

## CLI 命令

- `scan`：执行完整安全扫描。
- `check`：快速检查依赖漏洞。
- `fix`：调用 `npm audit fix` 进行自动修复。
- `license`：生成许可证合规报告。
- `sbom`：导出 SPDX / CycloneDX 格式的 SBOM。
- `report`：生成安全报告并写入扫描历史。
- `policy`：初始化、展示、验证安全策略配置。
- `monitor`：基于 cron 计划定时扫描。
- `watch`：启动持续监控模式，支持文件监听和 Git Hooks。
- `history`：查看历史记录与趋势分析。
- `compare`：比较两次扫描结果。
- `compliance`：按安全标准生成合规结果。
- `ci`：输出 CI 友好的扫描摘要，并根据阈值决定是否失败。
- `network-scan`：执行网络扫描。
- `system-info`：采集系统信息。
- `topology`：生成网络拓扑信息。

常用扫描选项：

- `--exclude <patterns>`：逗号分隔 glob 排除规则。
- `--severity <severity>`：只报告达到该级别及以上的问题。
- `--max-concurrency <number>`：限制扫描任务并发数，默认由扫描器控制。
- `--include-performance` / `--performance-report`：输出内联性能数据或落地 `.security-perf.json`。
- `scan --json --output <file>`：脚本友好的 JSON 输出与归档。

## 公开导出

### 包入口

- `@composy/security`：完整公共 API。
- `@composy/security/cli`：CLI 入口模块。
- `@composy/security/core`：核心扫描、自动化、策略、项目与缓存相关能力。
- `@composy/security/types`：稳定的类型模型导出。

### 核心模块

- `scanning/`：扫描器与分析器。
- `reporters/`：多格式报告器。
- `automation/`：调度、通知、自动修复。
- `providers/`：漏洞数据源与 Git 平台集成。
- `policy/`：策略加载、校验与规则引擎。
- `monitoring/`：持续监控。
- `history/`：扫描历史与趋势分析。
- `models/`：统一类型模型。

## 配置说明

策略文件加载时会校验字段结构、严重程度、报告格式和通知 URL。配置错误会直接报告并终止扫描，不会静默回退到默认策略；通知 URL 仅允许
`http` / `https` 协议。

策略配置默认按以下文件优先级查找：

- `.securityrc`
- `.securityrc.json`
- `.securityrc.js`
- `.securityrc.mjs`
- `.securityrc.cjs`
- `security.config.js`
- `security.config.mjs`
- `security.config.cjs`
- `security.config.json`
- `package.json` 中的 `security` 字段

生成 JavaScript 配置时，当前版本默认输出
`security.config.mjs`，从而同时兼容 ESM 项目与 Windows 路径加载。

出于安全考虑，JavaScript 策略文件默认不会执行。使用 `scan`、`report`、`ci` 或 `policy` 读取
`.js`、`.mjs`、`.cjs` 配置时，请显式传入 `--allow-executable-config`；JSON 配置无需额外开关。

## 开发与验证

```bash
pnpm run lint:check
pnpm run type-check
pnpm run test:run
pnpm run test:cli
pnpm run test:coverage
pnpm run build
```

`test:coverage` 使用 dist smoke runner 输出
`.ldesign-testing/smoke-coverage-summary.json`，用于当前 Windows/sandbox 环境中的稳定覆盖面记录；原生 Vitest 行覆盖率可在具备完整 coverage
provider 的环境中单独运行。

### 构建说明

- 构建工具使用 `@composy/pack`，其源码位于 `tools/tsup-config`。
- 当前包会打包 `src/**/*.ts` 中的所有源码入口（自动排除 `.d.ts` 声明文件）。
- 输出同时包含 ESM、CJS 与 `.d.ts`。

## 文档

- 架构说明：[`docs/guide/architecture.md`](./docs/guide/architecture.md)
- 配置指南：[`docs/configuration.md`](./docs/configuration.md)
- CLI 参考：[`docs/cliReference.md`](./docs/cliReference.md)
- 快速开始：[`docs/gettingStarted.md`](./docs/gettingStarted.md)
- 自定义扫描任务示例：[`examples/customRules/README.md`](./examples/customRules/README.md)

## 适用场景

- 本地开发阶段的安全自检。
- CI/CD 中的自动阻断与 SARIF 上传。
- 多项目或 monorepo 的集中安全巡检。
- 对许可证、SBOM 和供应链有额外审计要求的团队。
- 需要将扫描结果回写到 GitHub / GitLab 的自动化工作流。

## License

MIT

## 通过 `@composy/cli` 统一接入

<!-- ldesign-cli-integration:start -->

- 接入类型：`bin`
- 统一命令：`ldesign security`
- 命令别名：`sec`
- 包内原生 bin：`ldesign-security`、`lsec`

当前包通过独立 bin 接入，统一命令会转发到包自身 CLI。

```bash
pnpm add -D @composy/cli
ldesign security --help
ldesign tools run security --help
```

<!-- ldesign-cli-integration:end -->