https://github.com/julienloizelet/crowdsec-nodejs-bouncer
https://github.com/julienloizelet/crowdsec-nodejs-bouncer
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/julienloizelet/crowdsec-nodejs-bouncer
- Owner: julienloizelet
- License: mit
- Created: 2024-11-22T04:43:00.000Z (6 months ago)
- Default Branch: feat/various-updates
- Last Pushed: 2025-01-24T09:53:54.000Z (4 months ago)
- Last Synced: 2025-01-24T10:28:37.090Z (4 months ago)
- Language: TypeScript
- Size: 707 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
**Table of Contents** _generated with [DocToc](https://github.com/thlorenz/doctoc)_
- [CrowdSec NodeJS Bouncer](#crowdsec-nodejs-bouncer)
- [Basic Usage](#basic-usage)
- [Apply the remediation](#apply-the-remediation)
- [API](#api)
- [CrowdSecBouncer](#crowdsecbouncer)
- [Render ban wall](#render-ban-wall)
- [Render captcha wall](#render-captcha-wall)
- [MIT Licence](#mit-licence)
CrowdSec NodeJS Bouncer
✨ Crowdsec ✨
CrowdSec is a behavior detection engine that blocks common attacks like credential brute-force, port scans, and web scans.
It maintains a global IP reputation database, curated to avoid false positives, and shares it with all network members.
## Basic Usage
Invoking the bouncer is as simple as (Check our [examples](./examples)):
```typescript
import { CrowdSecBouncer, CrowdSecBouncerConfiguration } from '@crowdsec/nodejs-cs-bouncer';
const config: CrowdSecBouncerConfiguration = {
url: 'http://localhost:8080',
bouncerApiToken: 'your-api-key',
};
// Init the bouncer
const bouncer = new CrowdSecBouncer(config);
// Get the remediation for an IP
const remediation = await bouncer.getIpRemediation(malevolentIp);
```
### Apply the remediation
Thanks to the bouncer, you know the remediation about a given IP.
To apply the remediation you can use render methods offered by the library. You can either display a ban wall or a captcha wall (Check our [examples](./examples)):
```typescript
import { renderBanWall, BanWallOptions } from '@crowdsec/nodejs-cs-bouncer';
const wallOptions: BanWallOptions = {
texts: {
title: '⚠️ You have been banned ⚠️',
subtitle: 'You have been banned from accessing this website.',
},
};
// Render a full customizable HTML page
const banWall = await renderBanWall(wallOptions);
```
Example of a ban or captcha wall:
## API
### CrowdSecBouncer
[Check the initialization example](./examples/bouncer-init.ts)
- `constructor(config: CrowdSecBouncerConfiguration)` : Create a new instance of the CrowdSecBouncer.
- `CrowdSecBouncerConfiguration`
```typescript
{
url: 'string'; // The URL of your CrowdSec Local API
bouncerApiToken: 'string'; // The API token to use the bouncer
fallbackRemediation: 'RemediationType'; // The fallback remediation to use. Default: 'ban'
}
```
- `getIpRemediation(ip: string): Promise`: Get the remediation for a given IP.
### Render ban wall
- `renderBanWall(options: BanWallOptions): Promise`: Return a computed HTML page with the ban wall.
- `BanWallOptions` Default options:
```typescript
{
tabTitle: 'CrowdSec | Ban Wall', // The title of the tab
title: 'Access Denied', // Title present in the ban wall card
subtitle: 'This page is secured against cyber attacks, and your IP has been blocked by our system', // Subtitle present in the ban wall card
footer: '', // Footer present in the ban wall card
hideCrowdSecMentions: false, // Hide the CrowdSec mentions
colors: // Check default colors
texts: // Check default texts
}
```
### Render captcha wall
- `renderCaptchaWall(options: CaptchaWallOptions): Promise` : Return a computed HTML page with the captcha wall.
- `CaptchaWallOptions` Default options:
```typescript
{
tabTitle: 'CrowdSec | Captcha Wall', // The title of the tab
title: 'Access Denied', // Title present in the captcha wall card
subtitle: 'This page is secured against cyber attacks, and your IP has been blocked by our system', // Subtitle present in the captcha wall card
footer: '', // Footer present in the captcha wall card
hideCrowdSecMentions: false, // Hide the CrowdSec mentions
colors: // Check default colors
texts: // Check default texts
error: '', // The error message to show when the captcha validation fails
captchaImageTag: '', // The captcha image tag
redirectUrl: '', // The URL to redirect after the captcha validation
}
```
## MIT Licence
[MIT Licence](./LICENCE)