# VAULT PASSWORD MANAGER

Broglio Matteo - 899562\
Caputo Lorenzo - 894528 \
El Hanafi Nadim - 894489\
Fuso Valentina - 899972\
Giuggioli Daniel - 894415 

***Repo GitLab:*** https://gitlab.com/mbroglio/2025_assignment2_vaultPasswordManager.git

## DESCRIZIONE

Il progetto open source scelto consiste in un password manager da linea di comando che permette la memorizzazione sicura e la consultazione delle proprie password. \
Il software è scritto in Python e utilizza la libreria `sqlcipher` per la cifratura del database SQLite in cui sono memorizzate le password. \
Il lavoro svolto si concentra sull'implementazione di una pipeline DevOps per automatizzare il ciclo di vita del software dalla creazione alla distribuzione. \
Il progetto ha due branch principali: `main`, che contiene la versione stabile del codice, e `dev`, da noi creato, al fine di garantire la presenza di un ulteriore branch dedicato all'introduzioone di nuove funzionalità non ancora definitive. In particolar modo è stata aggiunta la funzionalità di classificazione delle password sulla base del loro livello di sicurezza. \
Di seguito la documentazione di ogni singola operazione (stage).


## DEFAULT
La prima fase consiste nel creare la configurazione di default. Automaticamente replicata prima di ogni stage. Prevede La selezione di un'immagine Docker, nello specifico Python 3.11-slim, questo sarà l'ambiente di esecuzione. Nello specifico ogni job della pipeline è preceduto da uno script, definito nella sezione before_script, che si occupa di installare le dipendenze di sistema necessarie per il suo corretto funzionamento.


##  STAGE BUILD

In questa fase, primo stage della pipeline, viene preparato l'ambiente di esecuzione per i successivi step.
Viene creato un ambiente virtuale Python utilizzando `venv`, che isola le dipendenze del progetto da quelle di sistema. \
Al fine di garantire compatibilità tra le librerie, viene effettuato l'aggiornamento di pip, lo strumento di gestione dei pacchetti Python dopodiché avviene l'effettivo import delle librerie tramite il file `requirements.txt`. \
Tale operazione viene eseguita su qualsiasi branch, in quanto necessaria per la corretta esecuzione di tutti gli stage successivi.

## STAGE VERIFY

Lo stage verify rappresenta la fase della pipeline in cui si effettua un controllo del codice, prima di proseguire alla fase di testing. In questa fase vengono eseguiti in parallelo due tool di analisi: Prospector (Analisi Statica) e Bandit (Controlli di Sicurezza). \
Sebbene vi siano due definizioni differenti, una per ciascun tool, il fatto di appartenere allo stesso stage implica che entrambi i job vengano eseguiti contemporaneamente. \
Lo stage viene implementato in qualsiasi branch, in quanto fondamentale per garantire la qualità del codice prima di procedere con i test.

### VERIFY PROSPECTOR

Prospector è uno strumento di analisi statica della qualità del codice. La configurazione `allow_failure: true` permette alla pipeline di continuare verso gli stage successivi anche se il job termina con un warning, che sono comunque notificati.

### VERIFY BANDIT

Bandit sfrutta l'analisi dell'_Abstract Syntax Tree (AST)_ per comprendere la struttura del codice e identificare costrutti potenzialmente pericolosi. Anche in questo caso la configurazione `allow_failure: true` è attiva per valutare i rischi senza necessariamente arrestare la pipeline.

## STAGE TEST

In questo stage viene verificato il corretto funzionamento del codice tramite l'esecuzione dei test indicati in `/src/unittest/test_vault.py`. Il plugin Coverage per Pytest (_pytest-cov_) permette di misurare la percentuale di codice effettivamente eseguita durante i test. Al termine, il comando `pytest --cov=. --cov-report=term` genera una tabella nella quale mostra, per ogni file:
- **Stmts:** numero totale di statement, o linee di codice eseguibili
- **Miss:** numero di statement non eseguiti durante i testi
- **Cover:** percentuale di statement coperti.
La configurazione del coverage `/TOTAL.*\s+(\d+%)$/` estrae la percentuale di coverage totale.\
Questo risulta essere l'ultimo stage eseguito su tutti i branch, in quanto fondamentale per garantire il corretto funzionamento del codice prima di procedere alla fase di packaging.

## STAGE PACKAGE

Lo stage Package trasforma il codice sorgente, verificato e testato, in pacchetti distribuibili e facilmente installabili in altri ambienti.\
Poiché in questa fase si crea un pacchetto in preparazione alla distribuzione, lo stage viene eseguito solo sul branch `main`.

## STAGE RELEASE

Come Package, viene eseguito solo sul branch `main`, e si occupa di pubblicare i pacchetti creati precedentemente su una repository pubblica come `PyPI`. Il comando `twine upload dist/* -u __token__ -p $PYPI_API_TOKEN` utilizza Twine come strumento di uploading, autenticandosi tramite un token API e variabili definite tramite GitLab CI/CD./
Il file setup.py contiene tutte le informazioni necessarie per la creazione e la distribuzione del pacchetto, come nome, versione, autore e dipendenze.

## STAGE DOCUMENTATION
Quest'ultimo stage, eseguito solo sul branch `main`, genera la docuementazione del progetto. Viene utilizzato `MkDocs`per convertire i file Markdown nella cartella `docs/` in un sito web HTML.