Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/smallwat3r/shhh
Share sensitive info without leaving a trace in your chat logs or email accounts.
https://github.com/smallwat3r/shhh
Last synced: 20 days ago
JSON representation
Share sensitive info without leaving a trace in your chat logs or email accounts.
- Host: GitHub
- URL: https://github.com/smallwat3r/shhh
- Owner: smallwat3r
- License: mit
- Created: 2019-09-17T20:46:53.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-04-12T21:40:39.000Z (8 months ago)
- Last Synced: 2024-04-13T05:26:26.400Z (8 months ago)
- Language: Python
- Homepage:
- Size: 24.9 MB
- Stars: 361
- Watchers: 11
- Forks: 31
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Keep secrets out of emails and chat logs.
## What is it?
**Shhh** is a tiny Flask app to create encrypted secrets and share
them securely with people. The goal of this application is to get rid
of plain text sensitive information into emails or chat logs.
Shhh is deployed [here](https://www.shhh-encrypt.com) (_temporary unavailable
until new deployment solution_), but **it's better for organisations and people
to deploy it on their own personal / private server** for even better security.
You can find in this repo everything you need to host the app yourself.
Or you can **one-click deploy to Heroku** using the below button.
It will generate a fully configured private instance of Shhh
immediately (using your own server running Flask behind Gunicorn and Nginx,
and your own PostgreSQL database). You can see the Heroku configuration files [here](https://github.com/smallwat3r/shhh-heroku-deploy/tree/main).
[![Deploy][heroku-shield]][heroku] (see [here](#initiate-the-database-tables) to
initiate the db tables after deploying on Heroku)
Also, checkout [shhh-cli](https://github.com/smallwat3r/shhh-cli),
a Go client to interact with the Shhh API from the command line.
## How does it work?
The sender has to set an expiration date along with a passphrase to
protect the information he wants to share.
A unique link is generated by Shhh that the sender can share with the
receiver in an email, alongside the temporary passphrase he created
in order to reveal the secret.
The secret will be **permanently removed** from the database as soon
as one of these events happens:
* the expiration date has passed.
* the receiver has decrypted the message.
* the amount of tries to open the secret has exceeded.
The secrets are encrypted in order to make the data anonymous,
especially in the database, and the passphrases are not stored
anywhere.
_Encryption method used: Fernet with password, random salt value and
strong iteration count (100 000)._
_Tip: for better security, avoid writing any info on how/where to use the secret you're sharing (like urls, websites or emails). Instead, explain this in your email or chat, with the link and passphrase generated from Shhh. So even if someone got access to your secret, there is no way for the attacker to know how and where to use it._
## Is there an API?
Yes, you can find some doc [here](https://app.swaggerhub.com/apis-docs/smallwat3r/shhh-api/1.0.0).
## How to launch Shhh?
These instructions are for development purpose only. For production
use you might want to use a more secure configuration.
#### Deps
The application will use the development env variables from [/environments/dev-docker-postgres.env](https://github.com/smallwat3r/shhh/blob/master/environments/dev-docker-postgres.env).
#### Docker
From the root of the repository, run
```sh
make dc-start # to start the app
make dc-start-adminer # to start the app with adminer (SQL editor)
make dc-stop # to stop the app
```
Once the container image has finished building and has started, you
can access:
* Shhh at
* Adminer at (if launched with `dc-start-adminer`)
_You can find the development database credentials from the env file at [/environments/dev-docker-postgres.env](https://github.com/smallwat3r/shhh/blob/master/environments/dev-docker-postgres.env)._
You have also the option to use `MySQL` instead of `PostgreSQL`, using these commands:
```sh
make dc-start-mysql # to start the app
make dc-start-adminer-mysql # to start the app with adminer (SQL editor)
make dc-stop-mysql # to stop the app
```
#### Migrations
Run the migrations using:
``` sh
make db c='upgrade'
```
If deployed on Heroku, you can run the migrations using:
``` sh
heroku run --app= python3 -m flask db upgrade
```
This will ensure the necessary tables are created and up-to-date in the database,
and make sure your deployed Shhh application works as expected.
You can write a revision using:
``` sh
make db c='revision "my revision"'
```
#### Development tools
You can run tests and linting / security reports using the Makefile.
Make sure you have `make`, `docker`, `yarn`, and a version of Python 3.12 installed on your machine.
Tests, linting, security tools do not run from the Docker container, so you need to have a Python
virtual environment configured locally.
You can do so with the following command:
``` sh
make venv deps
```
The following command will display all the commands available from the Makefile:
``` sh
make help
```
* Enter a Flask shell (from the running shhh container)
``` sh
make shell
```
* Run sanity checks
```sh
make tests # run tests
make ruff # run Ruff report
make bandit # run Bandit report
make mypy # run Mypy report
```
* Run code formatter
```sh
make yapf # format code using Yapf
```
* Generate frontend lockfile
```sh
make yarn # install the frontend deps using Yarn
```
## Environment variables
Bellow is the list of environment variables used by Shhh.
#### Mandatory
* `FLASK_ENV`: the environment config to load (`testing`, `dev-local`, `dev-docker`, `heroku`, `production`).
* `DB_HOST`: Database hostname
* `DB_USER`: Database username
* `DB_PASSWORD`: Database password
* `DB_NAME`: Database name
* `DB_ENGINE`: Database engine to use (ex: `postgresql+psycopg2`, `mysql+pymysql`)
Depending if you can use PostgreSQL or MySQL you might also need to set (these need to match the values
you've specified as `DB_NAME`, `DB_PASSWORD` and `DB_NAME` above):
* `POSTGRES_USER`: Postgresql username
* `POSTGRES_PASSWORD`: Postgresql password
* `POSTGRES_DB`: Postgresql database name
or
* `MYSQL_USER`: MySQL username
* `MYSQL_PASSWORD`: MySQL password
* `MYSQL_DATABASE`: MySQL database name
#### Optional
* `SHHH_HOST`: This variable can be used to specify a custom hostname to use as the
domain URL when Shhh creates a secret (ex: `https://`). If not set, the hostname
defaults to request.url_root, which should be fine in most cases.
* `SHHH_SECRET_MAX_LENGTH`: This variable manages how long the secrets your share with Shhh can
be. It defaults to 250 characters.
* `SHHH_DB_LIVENESS_RETRY_COUNT`: This variable manages the number of tries to reach the database
before performing a read or write operation. It could happens that the database is not reachable or is
asleep (for instance this happens often on Heroku free plans). The default retry number is 5.
* `SHHH_DB_LIVENESS_SLEEP_INTERVAL`: This variable manages the interval in seconds between the database
liveness retries. The default value is 1 second.
## License
See [LICENSE](https://github.com/smallwat3r/shhh/blob/master/LICENSE) file.
## Contact
Please report issues or questions
[here](https://github.com/smallwat3r/shhh/issues).
[![Buy me a coffee][buymeacoffee-shield]][buymeacoffee]
[buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-2.svg
[buymeacoffee]: https://www.buymeacoffee.com/smallwat3r
[heroku-shield]: https://www.herokucdn.com/deploy/button.svg
[heroku]: https://heroku.com/deploy?template=https://github.com/smallwat3r/shhh-heroku-deploy