diff --git a/README.md b/README.md index 971ed4e..ed2c6ae 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,14 @@ # Ansible KeePass Lookup Plugin -This collection provides a plugin that allows to read data from KeePass file (modifying is not supported) +This collection provides plugins that allows to read data from KeePass file (modifying is not supported) ## How it works -The plugin opens a UNIX socket with decrypted KeePass file. +The lookup plugin opens a UNIX socket with decrypted KeePass file. For performance reasons, decryption occurs only once at socket startup, and the KeePass file remains decrypted as long as the socket is open. The UNIX socket file is stored in a temporary folder according to OS. - ## Installation Requirements: `python 3`, `pykeepass==4.0.3` @@ -47,5 +46,17 @@ Use `ansible-vault encrypt_string` to encrypt it and use it like below ansible_become_pass : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'password') }}" custom_field : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'custom_properties', 'a_custom_property_name') }}" attachment : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'attachments', 'a_file_name') }}" + + - name: "Export file: attachment.txt" + viczem.keepass.attachment: + database: "{{ keepass_dbx }}" + password: "{{ keepass_psw }}" + entrypath: example/attachments + attachment: "attachment.txt" + dest: "{{ keepass_attachment_1_name }}" -More examples see in [/doc/examples](/doc/examples). +More examples see in [/docs/examples](/docs/examples). + +## Contributing + +See docs/contributing. \ No newline at end of file diff --git a/docs/contributing/README.md b/docs/contributing/README.md new file mode 100644 index 0000000..1007513 --- /dev/null +++ b/docs/contributing/README.md @@ -0,0 +1,29 @@ +# Contributing + +1. Create ansible.cfg in cloned directory: + +``` +[defaults] +COLLECTIONS_PATHS = ./collections +``` + +2. Create requirements.yml in cloned directory: + +``` +--- +collections: + - name: namespace.collection_name + source: /where/is/your/clone + type: dir +``` + + +3. To install the collection _locally_ in your cloned directory, just install it through ansible-galaxy +```shell +rm -rf ./collections && ansible-galaxy install -r requirements.yml +``` + +Note: Any change on your clone imply to reinstall the collection. + + +Tip: You can place a ansible.cfg with `COLLECTIONS_PATHS = ../../collections` in the examples dictory if you want to run the example on local collection in your cloned directory. diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 0000000..ade8370 --- /dev/null +++ b/docs/examples/README.md @@ -0,0 +1,5 @@ +# Example + +`ansible-playbook example-playbook.yml --ask-vault-pass -vvv` + +Password: `spamham` \ No newline at end of file diff --git a/docs/examples/example-playbook.yml b/docs/examples/example-playbook.yml new file mode 100644 index 0000000..6d27a23 --- /dev/null +++ b/docs/examples/example-playbook.yml @@ -0,0 +1,54 @@ +--- +- name: Example + hosts: 127.0.0.1 + connection: local + vars: + spam_login: "{{ lookup('viczem.keepass.keepass', 'spam', 'username') }}" + spam_password: "{{ lookup('viczem.keepass.keepass', 'spam', 'password') }}" + ham_login: "{{ lookup('viczem.keepass.keepass', 'example/ham', 'username') }}" + ham_password: "{{ lookup('viczem.keepass.keepass', 'example/ham', 'password') }}" + slash_login: "{{ lookup('viczem.keepass.keepass', 'slash\\/group/slash\\/title', 'username') }}" + slash_url: "{{ lookup('viczem.keepass.keepass', 'slash\\/group/slash\\/title', 'url') }}" + pork_custom_property: "{{ lookup('viczem.keepass.keepass', 'example/pork', 'custom_properties', 'pork_custom_property')}}" + attachment: "{{ lookup('viczem.keepass.keepass', 'example/pork', 'attachments', 'test.txt')}}" + keepass_attachment_1_name: "attachment_1.txt" + keepass_attachment_2_name: "attachment_2.zip" + + tasks: + - debug: + msg: "fetch entry: '/spam'; username: '{{ spam_login }}'; password: '{{ spam_password }}'" + + - debug: + msg: "fetch entry: '/examples/ham'; username: '{{ ham_login }}'; password: '{{ ham_password }}'" + + - debug: + msg: "fetch entry: '/examples/port'; attachments: 'text.txt' - '{{ attachment }}'" + + - name: pause to emulate long time operation (greater than keepass_ttl) + pause: + seconds: 5 + + - debug: + msg: "fetch entry: '/examples/pork'; custom_properties: 'pork_custom_property' - '{{ pork_custom_property }}'" + + - debug: + msg: "fetch entry: '/slash\\/group/slash\\/title'; username: '{{ slash_login }}'; url: '{{ slash_url }}'" + + - debug: "{{ lookup('viczem.keepass.keepass', 'close') }}" + + - name: "Export file: {{ keepass_attachment_1_name }}" + viczem.keepass.attachment: + database: "{{ keepass_dbx }}" + password: "{{ keepass_psw }}" + entrypath: example/attachments + attachment: "{{ keepass_attachment_1_name }}" + dest: "{{ keepass_attachment_1_name }}" + + - name: "Export file: {{ keepass_attachment_2_name }}" + viczem.keepass.attachment: + database: "{{ keepass_dbx }}" + password: "{{ keepass_psw }}" + entrypath: example/attachments + attachment: "{{ keepass_attachment_2_name }}" + dest: "{{ keepass_attachment_2_name }}" + mode: 0600 \ No newline at end of file diff --git a/docs/examples/example.kdbx b/docs/examples/example.kdbx new file mode 100644 index 0000000..127e279 Binary files /dev/null and b/docs/examples/example.kdbx differ diff --git a/docs/examples/group_vars/all b/docs/examples/group_vars/all new file mode 100644 index 0000000..679e175 --- /dev/null +++ b/docs/examples/group_vars/all @@ -0,0 +1,9 @@ +keepass_ttl: 3 +keepass_dbx: "./example.kdbx" +keepass_psw: !vault | + $ANSIBLE_VAULT;1.1;AES256 + 30656633313531336265353862356135373963636339376266373137376136636634393932623961 + 6138656232363861333932373066636237626232623566380a313964313733643532373139313636 + 62303365393630383037356334363332306239316566383061336263383134353139663161643331 + 3736316666613761380a646333353163633236323835313965313034373163343031616531393336 + 6538 diff --git a/galaxy.yml b/galaxy.yml index cd8af3e..7e12847 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -21,11 +21,11 @@ authors: ### OPTIONAL but strongly recommended # A short summary description of the collection -description: The collection provides a lookup plugin that allow to read data from KeePass file. +description: The collection provides plugins that allow to read data from KeePass file. # Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only # accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file' -license: [] +license: [MIT] # The path to the license file for the collection. This path is relative to the root of the collection. This key is # mutually exclusive with 'license' @@ -36,6 +36,7 @@ license_file: 'LICENSE' tags: - keepass - lookup + - module - plugin # Collections that this collection requires to be installed for it to be usable. The key of the dict is the