bitbucket.org/Aishee/synsec@v0.0.0-20210414005726-236fc01a153d/docker/README.md (about)

     1  # Synsec
     2  
     3  Synsec - An open-source, lightweight agent to detect and respond to bad behaviours. It also automatically benefits from our global community-wide IP reputation database.
     4  
     5  ## Getting Started
     6  
     7  Before starting using docker image, we suggest you to read our documentation to understand all [synsec concepts](https://docs.synsec.net/).
     8  
     9  #### Run
    10  
    11  The container is built with specific docker [configuration](https://bitbucket.org/Aishee/synsec/blob/master/docker/config.yaml) :
    12  
    13  You should apply following configuration before starting it :
    14  
    15  * Specify collections|scenarios|parsers/postoverflows to install via the environment variables (by default [`breakteam/linux`](https://hub.synsec.net/author/breakteam/collections/linux) is installed)
    16  * Mount volumes to specify your log files that should be ingested by synsec (set up in acquis.yaml)
    17  * Mount other volumes : if you want to share the database for example
    18  
    19  ```shell
    20  docker run -d -v acquis.yaml:/etc/synsec/acquis.yaml \
    21      -e COLLECTIONS="breakteam/sshd"
    22      -v /var/log/auth.log:/var/log/auth.log \
    23      -v /path/mycustom.log:/var/log/mycustom.log \
    24      --name synsec breakteam/synsec
    25  ```
    26  
    27  #### Example
    28  
    29  I have my own configuration :
    30  ```shell
    31  user@cs ~/synsec/config $ ls
    32  acquis.yaml  config.yaml
    33  ```
    34  
    35  Here is my acquis.yaml file:
    36  ```shell
    37  filenames:
    38   - /logs/auth.log
    39   - /logs/syslog
    40  labels:
    41    type: syslog
    42  ---
    43  filename: /logs/apache2/*.log
    44  labels:
    45    type: apache2
    46  ```
    47  
    48  So, I want to run synsec with :
    49  
    50  * My configuration files
    51  * Ingested my path logs specified in acquis.yaml
    52  * Share the synsec sqlite database with my host (You need to create empty file first, otherwise docker will create a directory instead of simple file)
    53  * Expose local API through host (listen by default on `8080`)
    54  * Expose prometheus handler through host (listen by default on `6060`)
    55  
    56  ```shell
    57  touch /path/myDatabase.db
    58  docker run -d -v config.yaml:/etc/synsec/config.yaml \
    59      -v acquis.yaml:/etc/synsec/acquis.yaml \
    60      -v /var/log/auth.log:/logs/auth.log \
    61      -v /var/log/syslog.log:/logs/syslog.log \
    62      -v /var/log/apache:/logs/apache \
    63      -v /path/myDatabase.db:/var/lib/synsec/data/synsec.db \
    64      -e COLLECTIONS="breakteam/apache2 breakteam/sshd" \
    65      -p 8080:8080 -p 6060:6060 \
    66      --name synsec breakteam/synsec
    67  ```
    68  
    69  If you want to be able to restart/stop your container and keep the same DB `-v /path/myDatabase.db:/var/lib/synsec/data/synsec.db` you need to add a volume on local_api_credentials.yaml `-v /path/local_api_credentials.yaml:/etc/synsec/local_api_credentials.yaml`.
    70  
    71  ### Environment Variables
    72  
    73  * `COLLECTIONS`             - Collections to install from the [hub](https://hub.synsec.net/browse/#collections), separated by space : `-e COLLECTIONS="breakteam/linux breakteam/apache2"`
    74  * `SCENARIOS`               - Scenarios to install from the [hub](https://hub.synsec.net/browse/#configurations), separated by space : `-e SCENARIOS="breakteam/http-bad-user-agent breakteam/http-xss-probing"`
    75  * `PARSERS`                 - Parsers to install from the [hub](https://hub.synsec.net/browse/#configurations), separated by space : `-e PARSERS="breakteam/http-logs breakteam/modsecurity"`
    76  * `POSTOVERFLOWS`           - Postoverflows to install from the [hub](https://hub.synsec.net/browse/#configurations), separated by space : `-e POSTOVERFLOWS="breakteam/cdn-whitelist"`
    77  * `CONFIG_FILE`             - Configuration file (default: `/etc/synsec/config.yaml`) : `-e CONFIG_FILE="<config_path>"`
    78  * `FILE_PATH`               - Process a single file in time-machine : `-e FILE_PATH="<file_path>"`
    79  * `JOURNALCTL_FILTER`       - Process a single journalctl output in time-machine : `-e JOURNALCTL_FILTER="<journalctl_filter>"`
    80  * `TYPE`                    - [`Labels.type`](https://docs.synsec.net/Synsec/v1/references/acquisition/) for file in time-machine : `-e TYPE="<type>"`
    81  * `TEST_MODE`               - Only test configs (default: `false`) : `-e TEST_MODE="<true|false>"`
    82  * `DISABLE_AGENT`           - Only test configs (default: `false`) : `-e DISABLE_AGENT="<true|false>"`
    83  * `DISABLE_LOCAL_API`       - Disable local API (default: `false`) : `-e DISABLE_API="<true|false>"`
    84  * `DISABLE_ONLINE_API`      - Disable Online API registration for signal sharing (default: `false`) : `-e DISABLE_ONLINE_API="<true|false>"`
    85  * `LEVEL_TRACE`             - Trace-level (VERY verbose) on stdout (default: `false`) : `-e LEVEL_TRACE="<true|false>"`
    86  * `LEVEL_DEBUG`             - Debug-level on stdout (default: `false`) : `-e LEVEL_DEBUG="<true|false>"`
    87  * `LEVEL_INFO`              - Info-level on stdout (default: `false`) : `-e LEVEL_INFO="<true|false>"`
    88  
    89  ### Volumes
    90  
    91  * `/var/lib/synsec/data/` - Directory where all synsec data (Databases) is located
    92  
    93  * `/etc/synsec/` - Directory where all synsec configurations are located
    94  
    95  #### Useful File Locations
    96  
    97  * `/usr/local/bin/synsec` - Synsec binary
    98    
    99  * `/usr/local/bin/ccscli` - Synsec CLI binary to interact with synsec
   100  
   101  ## Find Us
   102  
   103  * [GitHub](https://bitbucket.org/Aishee/synsec)
   104  
   105  ## Contributing
   106  
   107  Please read [contributing](https://docs.synsec.net/Synsec/v1/contributing/) for details on our code of conduct, and the process for submitting pull requests to us.
   108  
   109  ## License
   110  
   111  This project is licensed under the MIT License - see the [LICENSE](https://bitbucket.org/Aishee/synsec/blob/master/LICENSE) file for details.