<commit_before># Search Guard Security Plugin
Elasticsearch security for free.

Search Guard is a free and open source plugin for Elasticsearch which provides security features.

[![Build Status](https://travis-ci.org/floragunncom/search-guard.svg?branch=master)](https://travis-ci.org/floragunncom/search-guard) [![Coverage Status](https://coveralls.io/repos/floragunncom/search-guard/badge.svg?branch=master)](https://coveralls.io/r/floragunncom/search-guard?branch=master)

##Support
* Community support available via [google groups](https://groups.google.com/forum/#!forum/search-guard)
* Commercial support through [floragunn UG](http://floragunn.com) available soon

##Features
* Flexible REST layer access control (User/Role based; on aliases, indices and types)
* Flexible transport layer access control (User/Role based; on aliases, indices and types)
* Document level security (DLS): Retrieve only documents matching criterias
* Field level security (FLS): Filter out fields/sourceparts from a search response
* HTTP authentication (Basic, Proxy header, SPNEGO/Kerberos, Mutual SSL/CLIENT-CERT)
* HTTP session support through cookies
* Flexible authentication backends (LDAP(s)/Active Directory, File based, Proxy header, Native Windows through WAFFLE) 
* Flexible authorization backends (LDAP(s)/Active Directory, File based, Native Windows through WAFFLE) 
* Node-to-node encryption through SSL/TLS (Transport layer)
* Secure REST layer through HTTPS (SSL/TLS)
* X-Forwarded-For (XFF) support
* Audit logging
* Anonymous login/unauthenticated access
* Works with Kibana 4 and logstash

##Limitations
* When using DLS or FLS you can still search in all documents/fields but not all documents/fields are returned
* Transport layer access control only with simple username/password login
* No automatic multi index filters (see below)
* Currently monitoring of the cluster needs no authentication and is allowed always (this may change in the future)

##How it works
Basically Search Guard consists of an authentication, authorization, SSL/TLS, XFF, HTTP session and audit log module and access control. All of them without the exception of access control are more or less self-explanatory. But access control, the heart of Search Guard, needs some more attention.

Search Guard has the concept of routing a request through a chain of filters which can modify or block the request/response. There are currently 3 types of filters:

* **actionrequest/restrequest filter**: Checks if the user is allowed to perform actions (like read, write, admin actions …). Works generally, not only for search requests.
* **dls filter**: filters out documents from the search response
* **fls filter**: filter out fields from the documents of a search response

##Pre-Installation
###Check Release Integrity

You **must** verify the integrity of the downloaded files. We provide PGP signatures for every release file. This signature should be matched against the KEYS file. We also provide MD5 and SHA-1 checksums for every release file. After you download the file, you should calculate a checksum for your download, and make sure it is the same as ours. [Here](http://www.openoffice.org/download/checksums.html) and [here](https://www.apache.org/info/verification.html) are some tips how to verify the pgp signatures.

###Setup ACL rules

It's recommended to setup the access control rules (ACL rules) **before** installing the plugin to simplify the installation process.
If you install the plugin first you have to do extra effort cause then your're firstly locked-out of elasticsearch.

Why not install a ACL rules file which grants _all access_ for a user with role _admin_?

```javascript
curl -XPUT 'http://localhost:9200/searchguard/ac/ac' -d '{
    "acl": [
    {    
        "__Comment__": "By default no filters are executed and no filters a by-passed. In such a case a exception is throws an access will be denied.",
        "filters_bypass": [],
        "filters_execute": []
     },
     {
           "__Comment__": "For role *admin* all filters are bypassed (so none will be executed). This means unrestricted access.",
           "roles": [
               "admin"
           ],
           "filters_bypass": ["*"],
           "filters_execute": []
     }<commit_msg>Fix typos.<commit_after># Search Guard Security Plugin
Elasticsearch security for free.

Search Guard is a free and open source plugin for Elasticsearch which provides security features.

[![Build Status](https://travis-ci.org/floragunncom/search-guard.svg?branch=master)](https://travis-ci.org/floragunncom/search-guard) [![Coverage Status](https://coveralls.io/repos/floragunncom/search-guard/badge.svg?branch=master)](https://coveralls.io/r/floragunncom/search-guard?branch=master)

##Support
* Community support available via [google groups](https://groups.google.com/forum/#!forum/search-guard)
* Commercial support through [floragunn UG](http://floragunn.com) available soon

##Features
* Flexible REST layer access control (User/Role based; on aliases, indices and types)
* Flexible transport layer access control (User/Role based; on aliases, indices and types)
* Document level security (DLS): Retrieve only documents matching criterias
* Field level security (FLS): Filter out fields/sourceparts from a search response
* HTTP authentication (Basic, Proxy header, SPNEGO/Kerberos, Mutual SSL/CLIENT-CERT)
* HTTP session support through cookies
* Flexible authentication backends (LDAP(s)/Active Directory, File based, Proxy header, Native Windows through WAFFLE) 
* Flexible authorization backends (LDAP(s)/Active Directory, File based, Native Windows through WAFFLE) 
* Node-to-node encryption through SSL/TLS (Transport layer)
* Secure REST layer through HTTPS (SSL/TLS)
* X-Forwarded-For (XFF) support
* Audit logging
* Anonymous login/unauthenticated access
* Works with Kibana 4 and logstash

##Limitations
* When using DLS or FLS you can still search in all documents/fields but not all documents/fields are returned
* Transport layer access control only with simple username/password login
* No automatic multi index filters (see below)
* Currently monitoring of the cluster needs no authentication and is allowed always (this may change in the future)

##How it works
Basically Search Guard consists of an authentication, authorization, SSL/TLS, XFF, HTTP session and audit log module and access control. All of them without the exception of access control are more or less self-explanatory. But access control, the heart of Search Guard, needs some more attention.

Search Guard has the concept of routing a request through a chain of filters which can modify or block the request/response. There are currently 3 types of filters:

* **actionrequest/restrequest filter**: Checks if the user is allowed to perform actions (like read, write, admin actions …). Works generally, not only for search requests.
* **dls filter**: filters out documents from the search response
* **fls filter**: filter out fields from the documents of a search response

##Pre-Installation
###Check Release Integrity

You **must** verify the integrity of the downloaded files. We provide PGP signatures for every release file. This signature should be matched against the KEYS file. We also provide MD5 and SHA-1 checksums for every release file. After you download the file, you should calculate a checksum for your download, and make sure it is the same as ours. [Here](http://www.openoffice.org/download/checksums.html) and [here](https://www.apache.org/info/verification.html) are some tips how to verify the pgp signatures.

###Setup ACL rules

It's recommended to setup the access control rules (ACL rules) **before** installing the plugin to simplify the installation process.
If you install the plugin first you have to do extra effort cause then your're firstly locked-out of elasticsearch.

Why not install a ACL rules file which grants _all access_ for a user with role _admin_?

```javascript
curl -XPUT 'http://localhost:9200/searchguard/ac/ac' -d '{
    "acl": [
    {    
        "__Comment__": "By default no filters are executed and no filters a by-passed. In such a case an exception is thrown and access will be denied.",
        "filters_bypass": [],
        "filters_execute": []
     },
     {
           "__Comment__": "For role *admin* all filters are bypassed (so none will be executed). This means unrestricted access.",
           "roles": [
               "admin"
           ],
           "filters_bypass": ["*"],
           "filters_execute": []
     }
{'fraction_non_alphanumeric': 0.0829142790316922, 'fraction_numerical': 0.0018711261840720383, 'mean_word_length': 4.395583596214511, 'pattern_counts': {'":': 16, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 12, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '692383', 'n_tokens_mistral': 2253, 'n_tokens_neox': 2171, 'n_words': 1023}