Metadata-Version: 2.4
Name: digdeo-syspass-ansible-lookup
Version: 0.3.8
Summary: DigDeo - Ansible lookup plugin to retrieve passwords from SysPass password manager
Author-email: DigDeo <pierre-henry.muller@digdeo.fr>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup
Keywords: DigDeo,Syspass,Ansible,Lookup
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: digdeo-syspass-client
Requires-Dist: six
Requires-Dist: colorama
Dynamic: license-file

[![coverage report](https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup/badges/master/coverage.svg)](https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup/commits/master) [![pipeline status](https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup/badges/master/pipeline.svg)](https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup/commits/master)

# digdeo-syspass-ansible-lookup

**Module page**: https://pypi.org/project/digdeo-syspass-ansible-lookup/
**Bug Tracker**: https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup/issues

## Introduction
**digdeo-syspass-ansible-lookup** is an [Ansible](https://ansible.com) [lookup plugin](https://docs.ansible.com/ansible/latest/plugins/lookup.html) written in [Python](https://www.python.org).

This Ansible plugin uses [digdeo-syspass-client](https://pypi.org/project/digdeo-syspass-client/) to interface with the [SysPass](https://www.syspass.org) API.

This plugin is dedicated to retrieving passwords from a [SysPass](https://www.syspass.org) server.

## Installation

### Normal installation
```shell script
python3 -m venv venv
. venv/bin/activate
pip install digdeo-syspass-ansible-lookup
```

### Force a specific Ansible version
```shell script
python3 -m venv venv
. venv/bin/activate
pip install wheel "ansible >= 10.0"
pip install digdeo-syspass-ansible-lookup
```

### Force libxml

On Linux (and most other well-behaved operating systems), pip will manage to build the source distribution as long as ``libxml2`` and ``libxslt`` are properly installed, including development packages, i.e. header files, etc. 

See the requirements section above and use your system package management tool to look for packages like ``libxml2-dev`` or ``libxslt-devel``. If the build fails, make sure they are installed.

Alternatively, setting ``STATIC_DEPS=true`` will download and build both libraries automatically in their latest version, e.g. 

```shell script
STATIC_DEPS=true pip install lxml.
```


Note that module use [digdeo-syspass-client](https://pypi.org/project/digdeo-syspass-client/) python module 
Please pay attention about config.yml file in case you need more information's.


**DISCLAIMER:**<br>
This module has been heavily inspired by https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/lookup/password.py for password generation and term handling and thus is under GPL.

    lookup: syspass
    author: DigDeo Team
    short_description: get syspass user password and syspass API client
    description:
    - This lookup returns the contents from SysPass database, a user's password more specifically. Other functions are also implemented for further use.
    ansible_version: ansible 10.4+ with mitogen
    python_version: 3.7+
    syspass_version: 3.2
 
### Ansible usage:

#### Example 1
**Vars set inside common ansible sub-structure directory**

In case you use the group name `all`.

* Create a sub directory structure `./group_vars/all` and enter inside it directory
* copy paste you variable with right value inside a file name **syspass.yml**
```
syspass_auth_token: ##################################################
syspass_token_pass: ##################################################
syspass_verify_ssl: True
syspass_api_url: ##################################################
syspass_api_version: 3.1
syspass_debug: False
syspass_debug_level: 3
syspass_verbose: True
syspass_verbose_level: 3
```
* start you playbook with ``ansible-playbook playbook.yml``

#### Example 2 
**Vars set inside the playbook file**

In case you use the group name `all` the playbook can look like that:
```
--- # -*- mode: yaml; coding: utf-8 -*-

- hosts: all
  vars:
    syspass_default_length: 42
    syspass_auth_token: ##################################################
    syspass_token_pass: ##################################################
    syspass_verify_ssl: True
    syspass_api_url: ##################################################
    syspass_api_version: 3.1
    syspass_debug: False
    syspass_debug_level: 3
    syspass_verbose: True
    syspass_verbose_level: 3
  tasks:
    - name: SysPass | Force virtual Environement
      set_fact:
        ansible_python_interpreter: "/usr/bin/env python"
    - name: SysPass | Minimal test | get and if not exist insert
      debug:
        msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
      register: pass1
      changed_when: false
    - name: SysPass | Minimal test | get and compare
      debug:
        msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
      register: pass2
      changed_when: pass1.msg == pass2.msg
      failed_when: pass1.msg != pass2.msg
```

### Ansible Vault usage:

In case you use the group name `all`.

* Create a sub directory structure `./group_vars/all` and enter inside it directory
* use command line interface for create **syspass.yml** file `ansible-vault create syspass.yml`
* edit the **syspass.yml** file `ansible-vault edit syspass.yml`
* copy paste you variable with right value inside **syspass.yml** file
```
syspass_auth_token: ##################################################
syspass_token_pass: ##################################################
syspass_verify_ssl: True
syspass_api_url: ##################################################
syspass_api_version: 3.1
syspass_debug: False
syspass_debug_level: 3
syspass_verbose: True
syspass_verbose_level: 3
```
* create a file to store the vault password ``echo "password1234" > /my_directory/vault_passwd"``
* export env var ``DEFAULT_VAULT_PASSWORD_FILE`` via ``export DEFAULT_VAULT_PASSWORD_FILE="/my_directory/vault_passwd"``
* start you playbook with ``ansible-playbook --vault-password-file=$DEFAULT_VAULT_PASSWORD_FILE playbook.yml``

#### Summary
```
> cd directory_where_is_my_ansible.cfg_file
> mkdir -p group_vars/all
> cd group_vars/all
> ansible-vault create syspass.yml
New Vault password: 
Confirm New Vault password: 
> ansible-vault edit syspass.yml
Vault password:
syspass_auth_token: ##################################################
syspass_token_pass: ##################################################
syspass_verify_ssl: True
syspass_api_url: ##################################################
syspass_api_version: 3.1
syspass_debug: False
syspass_debug_level: 3
syspass_verbose: True
syspass_verbose_level: 3
~                                                                                                                                                                                         
~                                                                                                                                                                                         
~                                                                                                                                                                                         
~                                                                                                                                                                                         
-- INSERTION --    
^Z :wq
> export DEFAULT_VAULT_PASSWORD_FILE="/my_private_directory/vault_passwd"
> echo "password1234" > $DEFAULT_VAULT_PASSWORD_FILE
> cd directory_where_is_my_ansible.cfg_file
> ansible-playbook --vault-password-file=$DEFAULT_VAULT_PASSWORD_FILE playbooks/playbook.yml
```

Parameters:
-----------

- **chars**: (Optional)
     
     Type of chars used during a password generation, 
     
     Allowed value: ``ascii_letters``, ``digits``, ``allowed_punctuation``
     
     Default value: ['ascii_letters','digits','allowed_punctuation']
     
- **psswd_length**: (Optional)

     password length, during a password generation, that value is automatically clamped from ``password_length_min`` and ``password_length_max``

     Default value: 42
    
- **password**: (Optional)

     Directly impose a password, it shortcut the password generation
    
- **hostname**: (Optional is set by Ansible)

     Require by Ansible, it correspond to Ansible host, you can impose a specific host from here

- **account**: 
     
     Match with Syspass API Account https://syspass-doc.readthedocs.io/en/3.1/application/api.html#accounts
     
- **login**:
     
     login given to created account
     
- **category**:

     Match with Syspass API Categories https://syspass-doc.readthedocs.io/en/3.1/application/api.html#categories
     
- **customer**:

     Match with Syspass API Clients https://syspass-doc.readthedocs.io/en/3.1/application/api.html#clients
     
- **customer_desc**: (Optional)

     Match with Syspass API Clients creation/description https://syspass-doc.readthedocs.io/en/3.1/application/api.html#clients

- **tags**:

     Match with Syspass API Tags https://syspass-doc.readthedocs.io/en/3.1/application/api.html#tags
     
- **url**: 

     url given to created account (Optional)
     
- **notes**:

     notes given to created account (Optional)
     
- **state**:

     Default Value: ``present``
     Allowed Value: ``present`` or ``absent``
     
- **private**: self.private,

     is this password private for users who have access or public for all users in acl (default false)
     
- **privategroup**: self.privategroup,

    is private only for users in same group (default false)
    
- **expireDate**: self.expireDate

    expiration date given to created account (Optional)
    
    Allowed Value: Expire date in UNIX timestamp format

    
notes:
-----
- Account is only created if exact name has no match.
- A different field passed to an already existing account wont modify it.
- Utility of tokenPass: https://github.com/nuxsmin/sysPass/issues/994#issuecomment-409050974
- Rudimentary list of API accesses (Deprecated): https://github.com/nuxsmin/sysPass/blob/d0056d74a8a2845fb3841b02f4af5eac3e4975ed/lib/SP/Services/Api/ApiService.php#L175
- Usage of ansible vars: https://github.com/ansible/ansible/issues/33738#issuecomment-350819222
    
        syspass function list:
          SyspassClient:
            Account:
              -AccountSearch
              -AccountViewpass
              -AccountCreate
              -AccountDelete
              -AccountView
            Category:
              -CategorySearch
              -CategoryCreate
              -CategoryDelete
            Client:
              -ClientSearch
              -ClientCreate
              -ClientDelete
            Tag:
              -TagCreate
              -TagSearch
              -TagDelete
            UserGroup:
              - UserGroupCreate
              - UserGroupSearch
              - UserGroupDelete
            Others:
              -Backup

### IN PLAYBOOK ###

NOTE: Default values are handled 

##### USAGE 1 #####
```yamlex
    - name: SysPass | Minimal test | get and if not exist insert
      debug:
        msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
      register: pass1
      changed_when: false

    - name: SysPass | Minimal test | get and compare
      debug:
        msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
      register: pass2
      changed_when: pass1.msg == pass2.msg
      failed_when: pass1.msg != pass2.msg
```
**Author**: DigDeo Team
