https://github.com/pompelmi/pompelmi
File-upload malware scanning for Node.js. Express/Koa/Next.js adapters, ZIP deep-inspection, MIME/size checks, optional YARA.
https://github.com/pompelmi/pompelmi
antivirus api automation backend cli cybersecurity devops files filesystem javascript library module nodejs npm opensource scanner security server typescript web
Last synced: 9 days ago
JSON representation
File-upload malware scanning for Node.js. Express/Koa/Next.js adapters, ZIP deep-inspection, MIME/size checks, optional YARA.
- Host: GitHub
- URL: https://github.com/pompelmi/pompelmi
- Owner: pompelmi
- License: mit
- Created: 2025-07-25T10:51:35.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-12T10:44:11.000Z (8 months ago)
- Last Synced: 2025-08-12T12:37:23.439Z (8 months ago)
- Topics: antivirus, api, automation, backend, cli, cybersecurity, devops, files, filesystem, javascript, library, module, nodejs, npm, opensource, scanner, security, server, typescript, web
- Language: TypeScript
- Homepage: https://pompelmi.github.io/pompelmi/
- Size: 13.2 MB
- Stars: 26
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- venom - `pompelmi` - source route-level upload security for Node.js teams that need to inspect untrusted files before disk, object storage, previews, or downstream parsers. can files before storage to detect malware, MIME spoofing, and risky archives. (Analysis Tools)
- awesome-nodejs-security - pompelmi - Local-first file upload scanning for Node.js to inspect untrusted files before storage. (Security Hardening)
- awesome-security - Pompelmi - Node.js file-upload malware scanner with MIME sniffing, ZIP-bomb protection and optional YARA rules. (Web / Development)
- awesome-javascript - pompelmi - Fast file-upload malware scanning for Node.js. (Security / Runner)
- fucking-awesome-javascript - pompelmi - Fast file-upload malware scanning for Node.js. (Security / Runner)
README
Pompelmi
Local-first file upload scanning for Node.js.
Pompelmi inspects untrusted files before storage and helps you decide whether to allow, reject, or quarantine them before they reach downstream systems.
It is built for upload endpoints that cannot rely on filenames, extensions, or client-provided MIME types alone.
## Install
```bash
npm install pompelmi
```
Requires Node.js 18+.
## Quick Start
```ts
import { scanBytes } from 'pompelmi';
const report = await scanBytes(file.buffer, {
ctx: {
filename: file.originalname,
mimeType: file.mimetype,
size: file.size,
},
});
if (!report.ok) {
return res.status(422).json({
error: 'Upload blocked',
verdict: report.verdict,
reasons: report.reasons,
});
}
```
## What Problem It Solves
Upload endpoints are part of your attack surface. A renamed executable, a risky PDF, or a hostile archive can look harmless until it is stored, unpacked, served, or parsed by another system.
Pompelmi adds checks at the upload boundary for:
- MIME spoofing and magic-byte mismatches
- Archive abuse such as ZIP bombs, traversal, and deep nesting
- Polyglot files and risky document structures
- Optional YARA-based signature matching
The goal is simple: inspect first, store later.
## Why This Shape
- Plain Markdown, readable in GitHub and in a terminal
- Fast path first: install, example, then deeper links
- Minimal top-level detail, with docs and examples for everything else
## Ecosystem
- `pompelmi`
- `@pompelmi/express-middleware`
- `@pompelmi/koa-middleware`
- `@pompelmi/next-upload`
- `@pompelmi/nestjs-integration`
- `@pompelmi/fastify-plugin`
- `@pompelmi/ui-react`
- `@pompelmi/cli`
## Repository Layout
- `src/` core library
- `packages/` framework adapters and supporting packages
- `examples/` runnable examples
- `tests/` test coverage
- `website/` documentation site
## Development
```bash
pnpm install
pnpm test
pnpm build
```
## Links
- [Documentation](https://pompelmi.github.io/pompelmi/)
- [Examples](./examples)
- [Contributing](./CONTRIBUTING.md)
- [Security](./SECURITY.md)
- [Roadmap](./ROADMAP.md)
## License
[MIT](./LICENSE)