@tiny-owl-kit / tiny-owl-npm-scan
🦉扫描你的项目 package.json 从管理的CSV列表中获取恶意npm包。
功能
- ✅ 内置恶意包数据库 -默认使用管理列表进行扫描
- ✅同时扫描
dependencies和devDependencies - 🌐支持自定义CSV文件（本地或远程url）
- 📦作为CLI工具或在代码中以编程方式使用
- 🚀快速轻量级
- 💯TypeScript支持
安装
全局安装（CLI使用）
npm install -g @tiny-owl-kit/tiny-owl-npm-scan
本地安装（程序化使用）
npm install --save-dev @tiny-owl-kit/tiny-owl-npm-scan
CLI使用
重要: 从项目的根目录(您的 package.json 文件的位置)。
cd path-to-your-project
快速扫描与捆绑的恶意包列表
tiny-owl-npm-scan
该工具包含一个已知恶意npm包的精选列表。只需运行不带参数的命令来扫描您的项目。
使用自定义本地CSV文件扫描
tiny-owl-npm-scan path/to/malicious-packages.csv
使用自定义远程CSV文件进行扫描
tiny-owl-npm-scan https://example.com/malicious-packages.csv
使用npx（无需安装）
# Scan with bundled list
npx @tiny-owl-kit/tiny-owl-npm-scan
# Scan with custom list
npx @tiny-owl-kit/tiny-owl-npm-scan path/to/malicious-packages.csv
编程式的使用
import { scanPackages } from "@tiny-owl-kit/tiny-owl-npm-scan";
// Scan with bundled malicious package list (recommended)
const result = await scanPackages();
console.log(`Found ${result.found.length} malicious packages:`);
result.found.forEach((pkg) => console.log(`- ${pkg}`));
// Scan with custom CSV file
const customResult = await scanPackages("path/to/malicious-packages.csv");
// Scan with custom options
const advancedResult = await scanPackages("https://example.com/list.csv", {
packageJsonPath: "/path/to/package.json",
includeDevDependencies: false,
});
API
scanPackages(packageListSource?, options?)
主扫描功能，检查是否有来自恶意列表的包在您的项目中。
参数
- packageListSource （
string（可选）：CSV文件的路径或URL。如果没有提供，则使用捆绑的恶意包列表。 - 选项 （
ScanOptions可选):packageJsonPath（string)：包的路径。json文件。默认为package。当前工作目录下的JsonincludeDevDependencies（boolean)：是否在scan中包含devDependencies。默认为truecsvParser（function)：自定义CSV解析器功能
返回
Promise<ScanResult>：
{
found: string[]; // List of malicious packages found
totalScanned: number; // Total number of packages scanned
packageJsonPath: string; // Path to package.json that was scanned
}
效用函数
getDefaultCsvPath(): string
返回绑定的恶意包列表CSV文件的路径。
isUrl(str: string): boolean
检查字符串是否是有效的URL。
fetchUrl(url: string): Promise<string>
从URL获取内容。
parsePackageListCsv(csvContent: string): string[]
解析CSV内容并从第一列提取包名（跳过标题行）。
readDependencies(packageJsonPath: string, includeDevDependencies?: boolean): Record<string, string>
读取包。Json并提取依赖项。
CSV格式
CSV文件的第一列应该有包名：
package_name,description,severity
malicious-pkg-1,Description of issue,high
malicious-pkg-2,Another issue,medium
第一行（标题）将自动跳过。
退出代码
当作为CLI工具使用时：
- 0：未发现恶意软件包
- 1：发现恶意包或发生错误
示例
快速安全扫描（推荐）
# Use bundled malicious package list
tiny-owl-npm-scan
使用自定义GitHub URL
tiny-owl-npm-scan https://raw.githubusercontent.com/org/repo/main/malicious-packages.csv
集成在CI/CD中
添加到你的 package.json 脚本:
{
"scripts": {
"security:scan": "tiny-owl-npm-scan"
}
}
然后在CI管道中运行：
npm run security:scan
在Node.js中自定义扫描
import { scanPackages, ScanResult } from "@tiny-owl-kit/tiny-owl-npm-scan";
async function auditProject() {
// Use bundled list (recommended)
const result: ScanResult = await scanPackages();
if (result.found.length > 0) {
console.error("Security Alert!");
result.found.forEach((pkg) => {
console.error(`Malicious package detected: ${pkg}`);
});
process.exit(1);
}
}
auditProject();
开发
构建
npm run build
测试
npm test
以监视模式运行测试
npm run test:watch
报道
npm run test:coverage
贡献
欢迎投稿！请随时提交拉取请求。
许可证
麻省理工学院
安全
如发现有保安漏洞，请电邮至[[email protected]]。
致谢
由Tiny Owl团队使用🦉制作。