Developing for Govready-Q¶
These pages cover topics related to working with the source of GovReady-Q.
You may also want to refer to the Installation Guide.
Contents
Setting Up Your Development Environment¶
Follow instructions listed at Developer Environment
Management Commands¶
GovReadyQ’s manage.py
uses django.core.management
to orchestrate management commands.
Implementation¶
from django.core.management import execute_from_command_line
execute_from_command_line(sys.argv)
I will summarize the fantastic documentation the Django development team has for BaseCommand in order for you to create your own commands. Bottom line, we create a new class that inherits from the Django object BaseCommand
.
For this walk-through I will outline how the management command ./manage.py compliance_app
allows us to list all available app sources.
First and foremost we need to ensure we have a management/commands directory under the Django app of choice, in this example guidedmodules (which registers the command when guidedmodules is included in INSTALLED_APPS). Then a new file compliance_app.py for our compliance_app
command argument. In this file we import and inherit BaseCommand
into our new class. Adding some help text to remind us of this commands purpose.
Note
We are now in guidedmodules/management/commands/compliance_app.py
from django.core.management.base import BaseCommand
class Command(BaseCommand):
help = 'Creates a new compliance app. Lists available appsource names if no command-line arguments are given.'
We can now add override the handle
method which is the only required implementation. An overview provided here.
class Command(BaseCommand):
...
def handle(self, *args, **options):
# if no appsource specified
# Show valid appsources by iterating through all AppSource objects and prints the slug name and path
# other argument logic that includes appsource specified
For additional arguments compliance_app also overrides add_arguments
. Here we specify the argument to enter ('appsource'
), the number of arguments ("?"
), and its type (str
). These arguments are then implemented in the handle override.
class Command(BaseCommand):
...
def add_arguments(self, parser):
parser.add_argument('appsource', nargs="?", type=str)
parser.add_argument('--path', nargs="?", type=str)
parser.add_argument('appname', nargs="?", type=str)
...
Currently Implemented¶
guidedmodules
Command
Usage Notes
./manage.py apps_catalog
Lists all apps in the configured app stores
./manage.py assemble --init path/to/app assemble.yaml
creating an ‘empty’ YAML file for a given app
./manage.py assemble assemble.yaml outdir
Make a directory
mkdir outdir
. Then assemble the app’s output documents to an output
./manage.py assemble --startapps assemble.yaml
Start component apps automatically
./manage.py compliance_app
lists available app sources
./manage.py compliance_app mysource
creates a new local AppSource named mysource
./manage.py compliance_app mysource myapp
creates a new app at path/to/apps/myapp
./manage.py load_modules
Updates the system modules from the YAML specifications in AppSources
./manage.py upgrade_project
Upgrades a project to a new version of an app or associates it with a different compliance app
siteapp
Command
Usage Notes
./manage.py db_before_090
Check if version 0.9.0 migration has been run. Return “False” if database not initialized or 0.9.0 migrations has been run
./manage.py first_run
Interactively set up an initial user and organization
./manage.py first_run --non-interactive
Non-interactively set up an initial user and organization
./manage.py send_notification_emails
Sends emails for notifications
./manage.py send_notification_emails forever
Sends emails for notifications forever
./manage.py test_screenshots
Generate screenshots of the application using Selenium for creating test artifacts and documentation. Run on non-production servers only.
siteap.test_screenshots arguments
Note
Need chromedriver.exe available in PATH for Selenium
A throwaway test database is used so that this command cannot see any existing user data, and database changes are not persistent. However, it would not be advisable to run this command on a production system.
Examples:
Create screenshots for the FISMA Level app:
./manage.py test_screenshots --app-source '{ "slug": "govready-apps-dev", "type": "git", "url": "https://github.com/GovReady/govready-apps-dev", "path": "apps" }' \ --app govready-apps-dev/fisma_level \ --path screenshots.pdf
The
--app-source
argument can be repeated multiple times if more than one AppSource is needed to run the script.Create screenshots for authoring a new app and set (approximate) output image size:
./manage.py test_screenshots --author-new-app \ --path screenshots.pdf \ --size 1024x768
Argument
Usage Notes
./manage.py test_screenshots --org-name
The name of the temporary Organization that will be created.
./manage.py test_screenshots --app-source {source JSON}
An AppSource definition in JSON. This argument can be repeated.
./manage.py test_screenshots --app [source/app]
The AppSource slug plus app name of a compliance app to fill out.
./manage.py test_screenshots --test [testid]
The ID of the test to run defined in the app’s app.yaml ‘tests’ key, or @filename to load a test from a YAML file.
./manage.py test_screenshots --author-new-app
Take screenshots for Q documentation showing how to author a new compliance app.
./manage.py test_screenshots --path [dir_or_pdf]
The path to write screenshots into, either a directory or a filename ending with .pdf.
./manage.py test_screenshots --size [widthXheight]
The width and height, in pixels, of the headless web browser window, or ‘maximized’.
./manage.py test_screenshots --mouse-speed [seconds]
Each mouse move will have this duration.
./manage.py test_screenshots --version
Show program’s version number and exit
./manage.py test_screenshots -v {0,1,2,3}, --verbosity {0,1,2,3}
Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
./manage.py test_screenshots --settings SETTINGS
The Python path to a settings module, e.g. “myproject.settings.main”. If this isn’t provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
./manage.py test_screenshots --pythonpath PYTHONPATH
A directory to add to the Python path, e.g. “/home/djangoprojects/myproject”.
./manage.py test_screenshots --traceback
Raise on CommandError exceptions
./manage.py test_screenshots --no-color
Don’t colorize the command output.
./manage.py test_screenshots --force-color
Force colorization of the command output.
./manage.py test_screenshots --skip-checks
Skip system checks.
Handling Snyk Vulnerability Scanner Results¶
GovReady-Q uses Snyk for vulnerability scanning of python dependencies. The scanner runs in CircleCi at each push to the remote repository.
When a CircleCi build fails at the Snyk stage, this is most likely due to the fact that there is a dependency being used with a reported vulnerability as seen in this build fail example:

Take the following actions depending on the state of the vulnerability and how it is used in GovReady-Q:
1. Upgrade Package¶
In order to resolve the build fail, create a ticket to upgrade the vulnerable package to the latest version.
2. Avoid Using Vulnerable Code¶
If upgrading is not possible (ex. latest version has a vulnerability), ensure that the vulnerable portion of the package is not being used.
3. Downgrade If Necessary¶
If it is not possible to avoid using the package in a vulnerable manner, open a ticket to downgrade the package to the latest non-vulnerable version if possible.
Invitations on local systems¶
You will probably want to try the invite feature at some point. The debug server is configured to dump all outbound emails to the console. So if you “invite” others to join you within the application, you’ll need to go to the console to get the invitation acceptance link.