Skip to content

Commit

Permalink
Merge pull request #556 from crowdsecurity/fix_512
Browse files Browse the repository at this point in the history 
fix most of #512 issues
  • Loading branch information
@buixor
buixor authored Apr 4, 2024
2 parents 6930dce + e122237 commit 67dd6bc
Show file tree
Hide file tree
Showing 3 changed files with 84 additions and 49 deletions.
14 changes: 11 additions & 3 deletions crowdsec-docs/docs/appsec/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,15 +40,15 @@ A supplementary list of rules can be loaded during the out-of-band phase. These

### `inband_rules`

An optional list of rules to be loaded in inband phase. In band rules are blocking and evaluated before answering to the remediation component. Useful for virtual patching, rules with no/low false positives.
An optional list of rules to be loaded in inband phase. In band rules are blocking and evaluated before answering the remediation component. Useful for virtual patching, rules with no/low false positives.

### `default_remediation`

An optional remediation for inband rules, defaults to `block`.
An optional remediation for inband rules, defaults to `ban`. If set to `allow`, remediation component won't block the request (even if it matched rules). Any other value (including `captcha`) is passed as-is back to the remediation component.

### `default_pass_action`

An optional remediation for requests that didn't match any rules (or rules with a pass action). Defaults to nothing.
An optional remediation for requests that didn't match any rules (or rules with a pass action). Defaults to `allow`. Any other value will be passed as-is to the remediation component.

### `blocked_http_code`

Expand All @@ -58,6 +58,14 @@ The HTTP code to return to the remediation component when a request should be bl

The HTTP code to return to the remediation component when a request should not be blocked. Defaults to `200`

### `user_blocked_http_code`

The HTTP code to return to the final client when a request should be blocked. Defaults to `403`

### `user_passed_http_code`

The HTTP code to return to the final client when a request should not be blocked. Defaults to `200`

### `on_load`

See the [dedicated doc](/docs/appsec/hooks.md#on_load)
Expand Down
117 changes: 72 additions & 45 deletions crowdsec-docs/docs/appsec/hooks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,30 +16,46 @@ The three phases are:

Hooks are configured in your `appsec-config` file.

Except for the `on_load` hook, all hooks support a `filter` parameter and an `apply` parameter (`on_load` only has `apply`).
`on_load` hook only supports `apply`, while other hooks support `filter` and `apply` parameters.

Both `filter` and `apply` of the same phase have access to the same helpers.

Except for `on_load`, hooks can be called twice per request: once for in-band processing and once for out-of-band processing, thus it is recommended to use the `IsInBand` and `IsOutBand` variables to filter the hook.


Hooks have the following format:

```yaml
on_match:
- filter: IsInBand && 1 == 1
apply:
- valid expression
- valid expression
```
If the filter returns `true`, each of the expressions in the `apply` section are executed.


<!-- once https://github.com/crowdsecurity/crowdsec-docs/issues/555 is fixed, document on_success-->

### `on_load`

This hook is intended to be used to disable rules at loading (eg, to temporarily disable a rule that is causing false positives).


#### Available helpers

| Helper Name | Type | Description |
| --- | --- | --- |
| `RemoveInBandRuleByName` | `func(tag str)` | Disable the named in-band rule |
| `RemoveInBandRuleByTag` | `func(tag str)` | Disable the in-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveInBandRuleByID` | `func(id int)` | Disable the in-band rule identified by the ID |
| `RemoveOutBandRuleByName` | `func(tag str)` | Disable the named out-of-band rule |
| `RemoveOutBandRuleByTag` | `func(tag str)` | Disable the out-of-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveOutBandRuleByID` | `func(id int)` | Disable the out-of-band rule identified by the ID |
| `SetRemediationByTag` | `func(tag str, remediation string)` | Change the remediation of the in-band rule identified by the tag (multiple rules can have the same tag) |
| `SetRemediationByID` | `func(id int, remediation string)` | Change the remediation of the in-band rule identified by the ID |
| `SetRemediationByName` | `func(name str, remediation string)` | Change the remediation of the in-band rule identified by the name |
| Helper Name | Type | Description |
| ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `RemoveInBandRuleByName` | `func(tag str)` | Disable the named in-band rule |
| `RemoveInBandRuleByTag` | `func(tag str)` | Disable the in-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveInBandRuleByID` | `func(id int)` | Disable the in-band rule identified by the ID |
| `RemoveOutBandRuleByName` | `func(tag str)` | Disable the named out-of-band rule |
| `RemoveOutBandRuleByTag` | `func(tag str)` | Disable the out-of-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveOutBandRuleByID` | `func(id int)` | Disable the out-of-band rule identified by the ID |
| `SetRemediationByTag` | `func(tag str, remediation string)` | Change the remediation of the in-band rule identified by the tag (multiple rules can have the same tag) |
| `SetRemediationByID` | `func(id int, remediation string)` | Change the remediation of the in-band rule identified by the ID |
| `SetRemediationByName` | `func(name str, remediation string)` | Change the remediation of the in-band rule identified by the name |

##### Example

Expand All @@ -62,20 +78,20 @@ This hook is intended to be used to disable rules only for this particular reque

#### Available helpers

| Helper Name | Type | Description |
| --- | --- | --- |
| `RemoveInBandRuleByName` | `func(tag str)` | Disable the named in-band rule |
| `RemoveInBandRuleByTag` | `func(tag str)` | Disable the in-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveInBandRuleByID` | `func(id int)` | Disable the in-band rule identified by the ID |
| `RemoveOutBandRuleByName` | `func(tag str)` | Disable the named out-of-band rule |
| `RemoveOutBandRuleByTag` | `func(tag str)` | Disable the out-of-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveOutBandRuleByID` | `func(id int)` | Disable the out-of-band rule identified by the ID |
| `IsInBand` | `bool` | `true` if the request is in the in-band processing phase |
| `IsOutBand` | `bool` | `true` if the request is in the out-of-band processing phase |
| `SetRemediationByTag` | `func(tag str, remediation string)` | Change the remediation of the in-band rule identified by the tag (multiple rules can have the same tag) |
| `SetRemediationByID` | `func(id int, remediation string)` | Change the remediation of the in-band rule identified by the ID |
| `SetRemediationByName` | `func(name str, remediation string)` | Change the remediation of the in-band rule identified by the name |
| `req` | `http.Request` | Original HTTP request received by the remediation component |
| Helper Name | Type | Description |
| ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `RemoveInBandRuleByName` | `func(tag str)` | Disable the named in-band rule |
| `RemoveInBandRuleByTag` | `func(tag str)` | Disable the in-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveInBandRuleByID` | `func(id int)` | Disable the in-band rule identified by the ID |
| `RemoveOutBandRuleByName` | `func(tag str)` | Disable the named out-of-band rule |
| `RemoveOutBandRuleByTag` | `func(tag str)` | Disable the out-of-band rule identified by the tag (multiple rules can have the same tag) |
| `RemoveOutBandRuleByID` | `func(id int)` | Disable the out-of-band rule identified by the ID |
| `IsInBand` | `bool` | `true` if the request is in the in-band processing phase |
| `IsOutBand` | `bool` | `true` if the request is in the out-of-band processing phase |
| `SetRemediationByTag` | `func(tag str, remediation string)` | Change the remediation of the in-band rule identified by the tag (multiple rules can have the same tag) |
| `SetRemediationByID` | `func(id int, remediation string)` | Change the remediation of the in-band rule identified by the ID |
| `SetRemediationByName` | `func(name str, remediation string)` | Change the remediation of the in-band rule identified by the name |
| `req` | `http.Request` | Original HTTP request received by the remediation component |

#### Example

Expand All @@ -96,12 +112,12 @@ pre_eval:
This hook is mostly intended for debugging or threat-hunting purposes.

#### Available helpers
| Helper Name | Type | Description |
| --- | --- | --- |
| `IsInBand` | `bool` | `true` if the request is in the in-band processing phase |
| `IsOutBand` | `bool` | `true` if the request is in the out-of-band processing phase |
| `DumpRequest` | `func()` | Dump the request to a file |
| `req` | `http.Request` | Original HTTP request received by the remediation component |
| Helper Name | Type | Description |
| ------------- | -------------- | ------------------------------------------------------------ |
| `IsInBand` | `bool` | `true` if the request is in the in-band processing phase |
| `IsOutBand` | `bool` | `true` if the request is in the out-of-band processing phase |
| `DumpRequest` | `func()` | Dump the request to a file |
| `req` | `http.Request` | Original HTTP request received by the remediation component |

#### DumpRequest

Expand Down Expand Up @@ -149,19 +165,19 @@ This hook is intended to be used to change the behavior of the engine after a ma

#### Available helpers

| Helper Name | Type | Description |
| --- | --- | --- |
| Helper Name | Type | Description |
| ---------------- | -------------------------- | ------------------------------------------------------------------------- |
| `SetRemediation` | `func(remediation string)` | Change the remediation that will be returned to the remediation component |
| `SetReturnCode` | `func(code int)` | Change the HTTP code that will be returned to the remediation component |
| `CancelAlert` | `func()` | Prevent the Application Security Component to create a crowdsec alert |
| `SendAlert` | `func()` | Force the Application Security Component to create a crowdsec alert |
| `CancelEvent` | `func()` | Prevent the Application Security Component to create a crowdsec event |
| `SendEvent` | `func()` | Force the Application Security Component to create a crowdsec event |
| `DumpRequest` | `func()` | Dump the request to a file (see previous section for detailed usage) |
| `IsInBand` | `bool` | `true` if the request is in the in-band processing phase |
| `IsOutBand` | `bool` | `true` if the request is in the out-of-band processing phase |
| `evt` | `types.Event` | The event that has been generated by the Application Security Component |
| `req` | `http.Request` | Original HTTP request received by the remediation component |
| `SetReturnCode` | `func(code int)` | Change the HTTP code that will be returned to the remediation component |
| `CancelAlert` | `func()` | Prevent the Application Security Component to create a crowdsec alert |
| `SendAlert` | `func()` | Force the Application Security Component to create a crowdsec alert |
| `CancelEvent` | `func()` | Prevent the Application Security Component to create a crowdsec event |
| `SendEvent` | `func()` | Force the Application Security Component to create a crowdsec event |
| `DumpRequest` | `func()` | Dump the request to a file (see previous section for detailed usage) |
| `IsInBand` | `bool` | `true` if the request is in the in-band processing phase |
| `IsOutBand` | `bool` | `true` if the request is in the out-of-band processing phase |
| `evt` | `types.Event` | The event that has been generated by the Application Security Component |
| `req` | `http.Request` | Original HTTP request received by the remediation component |

#### Example

Expand All @@ -176,4 +192,15 @@ post_eval:
apply:
- CancelAlert()
- CancelEvent()
```
```

## Detailed Helpers Information

### `SetRemediation*`

When using `SetRemediation*` helpers, the only special value is `allow`: the remediation component won't block the request.
Any other values (including `ban` and `captcha`) are transmitted as-is to the remediation component.




2 changes: 1 addition & 1 deletion crowdsec-docs/docs/appsec/rules_syntax.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ Match provides the pattern to match the target against, including optional trans
- _(mandatory)_ `type` indicates the matching method, one of:

- `regex`: matches _target_ against value (_value_ is a RE2 regexp)
- `equal`: _target_ is a string equal to _value_
- `equals`: _target_ is a string equal to _value_
- `startsWith`: _target_ starts with _value_
- `endsWith`: _target_ ends with _value_
- `contains`: _target_ contains value
Expand Down

0 comments on commit 67dd6bc

Please sign in to comment.