> In the current example, we'll write a parser for the logs produced by `iptables` (netfilter) with the `-j LOG` target.
> This document aims at detailing the process of writing and testing new parsers.
## Base parser file
The most simple parser can be defined as :
```yaml
filter: 1 == 1
debug: true
onsuccess: next_stage
name: me/myparser
description: a cool parser for my service
grok:
#our grok pattern : capture .*
pattern: ^%{DATA:some_data}$
#the field to which we apply the grok pattern : the log message itself
apply_on: message
statics:
- parsed: is_my_service
value: yes
```
- a {{filter.htmlname}} : if the expression is `true`, the event will enter the parser, otherwise, it won't
- a {{onsuccess.htmlname}} : defines what happens when the {{event.htmlname}} was successfully parsed : shall we continue ? shall we move to next stage ? etc.
- a name & a description
- some {{statics.htmlname}} that will modify the {{event.htmlname}}
- a `debug` flag that allows to enable local debugging information.
We are going to use to following sample log as an example :
Using an [online grok debugger](https://grokdebug.herokuapp.com/) or an [online regex debugger](https://www.debuggex.com/), we come up with the following grok pattern :
Check if the pattern you are looking for is not already present in [patterns configuration](https://github.com/crowdsecurity/crowdsec/tree/master/config/patterns).
## Test our new pattern
Now, let's integrate our GROK pattern within our YAML :
```yaml
#let's set onsuccess to "next_stage" : if the log is parsed, we can consider it has been dealt with
onsuccess: next_stage
#debug, for reasons (don't do this in production)
debug: true
#as seen in our sample log, those logs are processed by the system and have a progname set to 'kernel'
DEBU[0000] Event leaving node : ok id=shy-forest name=crowdsecurity/iptables-logs stage=s01-parser
DEBU[0000] move Event from stage s01-parser to s02-enrich id=shy-forest name=crowdsecurity/iptables-logs stage=s01-parser
...
```
</details>
## Closing word
We have now a fully functional parser for {{crowdsec.name}} !
We can either deploy it to our production systems to do stuff, or even better, contribute to the {{hub.htmlname}} !
<!--
The first field that you will write is the `onsuccess` one. This one indicate what to do in case of success log parsing. Put the value `next_stage` if you want the log to be processed by the next stages in case of parsing success:
```yaml
onsuccess: next_stage
```
Then come the `filter` part.
You will mostly want to filter on the `program` of the event:
```yaml
filter: evt.Parsed.program == '<program>'
```
The `name` (please name your parser like `<github_account_name>/<parser_name>`):
```yaml
name: crowdsecurity/example
```
A small description:
```yaml
description: this parser can process X/Y/Z logs from <program>
```
The grok part:
- If you have only one type of log then you can start with the `grok` object which is defined as below:
```yaml
grok:
pattern: <your_grok_pattern_here> # can't be used with 'name'
name: <grok_name> # grok name loaded from https://github.com/crowdsecurity/crowdsec/tree/master/config/patterns. can't be used with 'pattern'
apply_on: message
statics:
-<meta|target> : <field_name>
<value|expression> : <field_value>
-<meta|target> : <field_name>
<value|expression> : <field_value>
```
The grok pattern will be applied on the `message` field of the previous success stage.
The `pattern` and `name` keyword can't be use together
- If you have more type of logs, you will have to start with the `node` keyword that is a list of grok:
```yaml
nodes:
grok:
pattern: <your_first_grok_pattern>
apply_on: message
statics:
-<meta|target> : <field_name>
<value|expression> : <field_value>
-<meta|target> : <field_name>
<value|expression> : <field_value>
grok:
pattern: <your_second_grok_pattern>
apply_on: message
statics:
-<meta|target> : <field_name>
<value|expression> : <field_value>
-<meta|target> : <field_name>
<value|expression> : <field_value>
statics:
-<meta|target> : <field_name>
<value|expression> : <field_value>
-<meta|target> : <field_name>
<value|expression> : <field_value>
```
The `statics` is a process that will set up a value for a given key in the parsed event.
For the field `name` the keyword can be either `meta` or `target`:
-`meta` : the new field will be created in the evt.Meta object to be accessible like : `evt.Meta.<new_field>`;
```yaml
meta: log_type
```
-`target`: the name of the new field:
```yaml
target: evt.source_ip
```
For the field value, it can be either `value` or `expression`:
-`value` is the value assigned, for example : `http_access_log`
```yaml
value: http_access_log
```
-`expression` the result of a parsed field, for example : `evt.Parsed.remote_addr`
```yaml
expression : evt.Parsed.remote_addr
```
The `statics` can be applied only for the grok it succeed, if it is in the `grok` object, else for whatever grok if at the root level.
