Contributions are welcome in the form of code or testing feedback. All contributors are expected to follow our code of conduct.
User feedback helps logdissect get better. All issues and comments can be directed to the issues page on GitHub, or emailed to [email protected]. Please ensure you are using the latest release.
Issues based on bugs should be well documented, with any error message and an explanation of how the issue can be reproduced. Additional information such as Python version and operating system are also useful.
If you have a bug fix, or an idea for a module, we would love to hear about it! You can start an issue on GitHub, or email the author at [email protected].
All new modules should be based on the dev branch. New modules usually don't require any editing of existing files (except __init__.py files), so conflicts shouldn't be much of an issue. Get in touch beforehand if you need to change other existing files for your module, or if you want to add to logdissect.utils.
Code should run with both Python 2 and 3. Coding style should be as simple and readable as possible. Variable names should tell you exactly what a variable does. Use four spaces for indentation (no tabs), and avoid one-liners; equivalent blocks of code are usually easier to read.
Creating a parser module is as simple as coming up with a regular expression, and some fields for it to parse. Parse modules are not limited to built-in fields; any field names can be defined. There is an example blank parser in logdissect/parsers/blank.py. Set the datestamp_type attribute for automatic date stamp conversion, which is required for merging and sorting logs. The options for datestamp_type are as follows:
standard- Standard syslog date stampsnodate- Time stamps with no date (i.e. tcpdump)iso- ISO8601 timestampsunix- Unix timestampsnow- Always set date stamp to time parsedNone- Skip conversion
Parse modules also have a post_parse_action method that each entry is passed through after it is parsed. This can be used for separating ports from source and destination hosts, or any other customization. By default, it does nothing.
The name of your parse module should be added to the __all__ variable and imported in logdissect/parsers/__init__.py. More information on parser modules can be found in the API documentation.
Creating a filter module is a bit more difficult. Check out the filter API documentation, and look at existing filter modules to get an idea of how filters work. There is an example blank filter in logdissect/filters/blank.py. Once you have created a filter module, add it to the all variable and import it in logdissect/filters/__init__.py.
Check out the output API documentation, and look at existing output modules to get an idea of how outputs work. There is an example blank output in logdissect/output/blank.py. Once you have created an output module, add it to the all variable and import it in logdissect/output/__init__.py.
To install the latest development version of logdissect from source, follow these instructioons:
Requirements: git, python-setuptools
git clone https://github.com/dogoncouch/logdissect.git
cd logdissect
git checkout dev
sudo make all
For usage instructions, see README.md.
For API documentation, see README-API.md