https://github.com/bymehul/nullspace
SSRF prevention library
https://github.com/bymehul/nullspace
nodejs security ssrf typescript
Last synced: 12 days ago
JSON representation
SSRF prevention library
- Host: GitHub
- URL: https://github.com/bymehul/nullspace
- Owner: bymehul
- License: mit
- Created: 2025-12-31T17:29:47.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-07-03T12:21:08.000Z (20 days ago)
- Last Synced: 2026-07-03T14:20:38.255Z (20 days ago)
- Topics: nodejs, security, ssrf, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/nullspace
- Size: 85.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nullspace
Security-first SSRF protection for Node.js outbound HTTP requests.
`nullspace` validates URLs, blocks private/internal ranges, defends against DNS rebinding, and pins connections to validated IPs.
## Installation
```bash
npm install nullspace
```
## Quick Start
```typescript
import { safeFetch, validateURL, isIPAllowed } from 'nullspace';
const response = await safeFetch('https://api.example.com/data');
const check = await validateURL('https://api.example.com/data');
if (!check.valid) {
console.error(check.errorCode, check.error);
}
isIPAllowed('8.8.8.8'); // true
isIPAllowed('127.0.0.1'); // false
isIPAllowed('169.254.169.254'); // false
```
## Key Protections
- Restricts protocols to `http` and `https`.
- Blocks loopback, private, link-local, metadata, multicast, and reserved ranges.
- Handles IPv4 encoding tricks (decimal, octal, hex, short forms).
- Handles IPv6 edge cases (`::1`, mapped IPv4, NAT64 embeddings).
- Rejects hostnames when any resolved record is internal.
- Resolves CNAME chains with loop and recursion-depth protection.
- Uses DNS cache floor plus socket pinning for rebinding resistance.
- Enforces response size, response header size, redirect count, and total timeout limits.
## Example Options
```typescript
await safeFetch('https://api.example.com', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ok: true }),
followRedirects: true,
maxRedirects: 5,
connectTimeout: 5000,
responseTimeout: 30000,
totalTimeout: 60000,
maxResponseSize: 10 * 1024 * 1024,
maxResponseHeadersSize: 32 * 1024,
allowedHostnames: ['api.example.com'],
});
```
## Documentation
- Usage examples: [how-to-use.md](./how-to-use.md)
- Technical reference: [docs.md](./docs.md)
## License
MIT