diff --git a/Dockerfile b/Dockerfile index 22b8044e..5709c383 100644 --- a/Dockerfile +++ b/Dockerfile @@ -16,11 +16,13 @@ RUN DEBIAN_FRONTEND=noninteractive \ # Set env variables used in this Dockerfile (add a unique prefix, such as DEV) RUN apt update && apt install -y netcat dnsutils libmariadbclient-dev +RUN mkdir -p /ebs/logs && touch /ebs/logs/engima.log && chmod 777 /ebs/logs/engima.log + ARG APPUID=1001 RUN useradd -rm -d /home/app -s /bin/bash -g root -G sudo -u "$APPUID" app WORKDIR /srv/code/dev RUN mkdir -p logs -RUN chown -R app /srv/code/dev +RUN chown -R app /srv/code/dev /ebs USER app diff --git a/Makefile b/Makefile index 2e0d08d5..992bbc98 100644 --- a/Makefile +++ b/Makefile @@ -24,9 +24,16 @@ dev: setup_mounts ## make build : Build and start docker containers - (web and db) .PHONY: build +build: export APPUID = $(APP_UID) build: @docker-compose up --build -d web +## make build_only : Only build the web container +.PHONY: build_only +build_only: export APPUID = $(APP_UID) +build_only: + @docker-compose build web + .PHONY: down down: export APPUID = $(APP_UID) down: @@ -73,4 +80,4 @@ schema_validate: @echo $(shell python3 scripts/clone_access_modules.py && python3 scripts/validator.py) run_semgrep: - $(shell semgrep --error --config "p/cwe-top-25" --config "p/owasp-top-ten" --config "p/r2c-security-audit") + $(shell semgrep --error --config "p/cwe-top-25" --config "p/r2c-security-audit") diff --git a/README.md b/README.md index bca143bb..6c7fd789 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,49 @@ -# enigma-public-central -Central Codebase for access management tool +## Enigma Access Management -### For contributing code +![BrowserStack Logo](https://d98b8t1nnulk5.cloudfront.net/production/images/layout/logo-header.png?1469004780) + +This tool consists of 2 different components: a central webserver and pluggable access modules. + +This repo is the code-base for the central webserver. +Refer to [this](https://github.com/browserstack/enigma-public-access-modules) for published access modules with this tool. + +Refer to [this doc](/docs/%E2%80%9CHow-to%E2%80%9D%20guides/Adding%20Modules.md) on how to create custom access modules + +## Usage + +The following steps are for hosting Enigma locally from published docker container images. + +For development setup, follow this [doc](/docs/one-click-dev.md) + +### Pre-requisistes + +You will need to have docker daemon running locally to run the published containers. +If you don't have docker setup, follow the guidelines [here](https://docs.docker.com/get-docker/) + +### Steps + +1. Ensure you have a valid `config.json` present locally. + +The default [config.json.sample](https://github.com/browserstack/enigma-public-central/blob/main/config.json.sample) should be sufficient to start. + +You can then add module-specific configuration for the modules you want integrated with Enigma. +For detailed instructions on configuration, follow [this doc](/docs/Configuration%20Guide.md) + +2. Run the enigma docker container by mounting the downloaded config to the container + +```bash +docker run --rm --name enigma -p 8000:8000 -v "$(pwd)/config.json":/srv/code/dev/config.json browserstack/enigma:v1 +``` + +Ensure that you 8000 port is free to use, and ensure that path to config.json is correct. + +That's it! Enigma should be running locally on port 8000 + + +For first time user sign-in, follow [this doc](/docs/%E2%80%9CHow-to%E2%80%9D%20guides/User%20Guides/First%20User%20Setup.md) + + +## Contributing code - Python 3.11.0 - pre-commit (see rules [below](#rules-enforced-by-the-pre-commit-hooks)) @@ -11,7 +53,7 @@ Central Codebase for access management tool - run: `pre-commit autoupdate` - run: `pre-commit run --all-files --show-diff-on-failure --color always` -## Commit Message Guideline +### Commit Message Guideline Format: `(): ` @@ -32,7 +74,7 @@ Format: `(): ` - `perf`: a code change that improves performance - `revert`: revert to a commit -## Example +### Example ``` feat: add hat wobble diff --git a/config.json.sample b/config.json.sample index 87d10d9c..baa04c3b 100644 --- a/config.json.sample +++ b/config.json.sample @@ -1,6 +1,6 @@ { "django_setup": { - "SECRET_KEY": "", + "SECRET_KEY": "random_secret_that_you_should_change_on_production", "DEBUG": false, "ALLOWED_HOSTS": [ "localhost" diff --git a/docker-compose.yml b/docker-compose.yml index e25adfb9..c7bc1cf2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,6 +2,7 @@ version: '3' services: web: container_name: dev + image: browserstack/enigma:v1 build: context: . dockerfile: Dockerfile @@ -19,9 +20,6 @@ services: - 8000:8000 depends_on: - db - command: > - bash -c "echo Starting Django runserver; - python manage.py runserver --insecure 0.0.0.0:8000" db: container_name: db image: mysql/mysql-server:8.0.31 diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh index b6c6f7f6..ac79c6ae 100755 --- a/docker-entrypoint.sh +++ b/docker-entrypoint.sh @@ -3,6 +3,17 @@ LOG_FILE=/ebs/logs/enigma.log CONTAINER_HASH=$(echo $RANDOM | md5sum | head -c 20) +trap ctrl_c INT + +pid_to_kill=1 +should_continue=0 + +function ctrl_c() { + echo "===== Stopping Service with pid $pid_to_kill =====" + kill $pid_to_kill + should_continue=1 +} + function log() { echo "$(date): $CONTAINER_HASH $@" 2>&1 | tee -a $LOG_FILE } @@ -34,4 +45,18 @@ log "===== Ensure Logs =====" touch /ebs/logs/enigma.log log "===== Running Service =====" -eval "$@" 2>&1 | prepend +if [ "$#" -ne 0 ]; then + eval "$@" 2>&1 | prepend +else + echo "===== Starting Webserver =====" + python manage.py runserver --insecure 0.0.0.0:8000 2>&1 & + pid_to_kill=$! + echo "Server PID $pid_to_kill" + + while true; do + if [ "$should_continue" -ne 0 ]; then + break + fi + sleep 5 + done +fi diff --git "a/docs/\342\200\234How-to\342\200\235 guides/Adding Modules.md" "b/docs/\342\200\234How-to\342\200\235 guides/Adding Modules.md" index 5fa35c9b..2f265b3a 100644 --- "a/docs/\342\200\234How-to\342\200\235 guides/Adding Modules.md" +++ "b/docs/\342\200\234How-to\342\200\235 guides/Adding Modules.md" @@ -1,4 +1,4 @@ -This document describes how to add modules on Enigma. +# How to add modules on Enigma. Enigma’s access management is built on modules, which refer to the resources/applications the user requires. Each module needs to be added and integrated with Enigma's central code in order to provide access for the user. @@ -12,7 +12,10 @@ Enigma provides the following modules as part of its default settings, these can 6. Slack 7. Zoom -When a new resource is required, it's corresponding module has to be added in [Engima's modules repository](https://github.com/browserstack/enigma-public-access-modules.git) or it's own (as per the usecase): +## Creating custom access modules + +When a new resource is required, it's corresponding module has to be added in [Engima's modules repository](https://github.com/browserstack/enigma-public-access-modules.git) or a new dedicated repo (as per the usecase): + - Add `__init__.py`: ```bash diff --git "a/docs/\342\200\234How-to\342\200\235 guides/Adding Users.md" "b/docs/\342\200\234How-to\342\200\235 guides/Adding Users.md" index 16e60ef0..b7f9d8f6 100644 --- "a/docs/\342\200\234How-to\342\200\235 guides/Adding Users.md" +++ "b/docs/\342\200\234How-to\342\200\235 guides/Adding Users.md" @@ -1,27 +1,40 @@ -This document describes how to add users on Enigma. +# How to add users on Enigma -## Create users on Enigma: -1. Manual Creation: +## Manual Creation - To manually create a user, login as superuser into the admin portal: +To manually create a user, login as superuser into the admin portal: - (i) Add user in "Authentication and Authorization administration". +- Add user in "Authentication and Authorization administration" section. - ``` Set email to user email id and password to anything you want. Save user details. ``` +Set email to user email id and password to anything you want. Save user details. - (ii) Add new user in "Access" and save. +- Add new user in "Access" and save. - (iii) The user can now log on to Enigma using the credentials set in Step (i) -2. Google SSO: - ### Add the config of googleapi in `config.json` - ```bash - .... - "sso": { - "googleapi": { - "SOCIAL_AUTH_GOOGLE_OAUTH2_KEY": "", - "SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET": "" - } +- The user can now log on to Enigma using the credentials. + +## Allow all users to sign-in with Google SSO + +### Obtain google OAuth key and secret + +Follow the steps [here](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred) to generate `client_secret.json` file. + + +The content of the file will have `client_id` key in `web` section. This is `SOCIAL_AUTH_GOOGLE_OAUTH2_KEY` in the below config. + + +The value for `client_secret` in `web` section is for `SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET`. + +### Add the config of googleapi in `config.json` + +```bash +.... +"sso": { + "googleapi": { + "SOCIAL_AUTH_GOOGLE_OAUTH2_KEY": "", + "SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET": "" } - .... - ``` +} +.... +``` + Sign in to enigma using your Google Mail to create a user on Enigma. diff --git "a/docs/\342\200\234How-to\342\200\235 guides/User Guides/First User Setup.md" "b/docs/\342\200\234How-to\342\200\235 guides/User Guides/First User Setup.md" new file mode 100644 index 00000000..a95abbbe --- /dev/null +++ "b/docs/\342\200\234How-to\342\200\235 guides/User Guides/First User Setup.md" @@ -0,0 +1,36 @@ +# First User Setup + +To setup admin user on enigma, follow these steps: + +1. Setup django superuser + +- Exec into the Enigma container + +```bash +docker exec -it enigma bash +``` + +- Run the following command in the container to create a superuser + +```bash +python manage.py createsuperuser +``` + +- Fill in the `username`, `email` and `password` for admin user + +Detailed instructions are available [here](https://docs.djangoproject.com/en/1.8/intro/tutorial02/#creating-an-admin-user) + +2. Sign-in into the admin site + +- Login to the admin site with the credentials created above. + +The admin site should be available at `/admin` with the base url on which enigma is hosted. + +This will be `http://localhost:8000/admin` if you are running this locally + +3. Now you can view the Enigma app dashboard, by navigating to enigma url. + +This will be `http://localhost:8000/` if you are running this locally + + +To create additional users, follow the doc [here](/docs/%E2%80%9CHow-to%E2%80%9D%20guides/Managing%20Groups/Adding%20Users.md) diff --git a/scripts/clone_access_modules.py b/scripts/clone_access_modules.py index c17dd4dc..c7149c9a 100644 --- a/scripts/clone_access_modules.py +++ b/scripts/clone_access_modules.py @@ -30,7 +30,6 @@ if not os.path.exists(requirements_file): open(requirements_file, 'w').close() - print("All urls: %s" % (",".join(urls))) for url in urls: specified_branch = None if "#" in url: