This repository contains best-practice guidance and - where appropriate - policy for Ministry of Justice (MoJ) technology security.
The information ranges from formal content, such as 'you must'-style documents, through to more informal help and suggestions, such as checklists.
The content is used to help build and operate products and services at the MoJ.
The work is performed in the open by intent, and for compliance with principle. Re-use of these materials outside of MoJ purposes must be in accordance with the published license.
Note: As a vibrant, dynamic, work-in progress, this material should not necessarily be treated as formal, finished, definitive, or accurate.
This repo is inspired by, and borrows from, GDS's technical guidance site and MoJ's technical guidance.
Content in the main
branch is created in DITA format, and stored in the dita
directory. When a build is required, the builder.ant
script in the buildUtils
directory is run. By default, it creates Markdown, PDF, and EPUB format output. The result output documents are put into a clean docs
directory.
Content in the docs
directory can be built and previewed using Jekyll, and hosted using GitHub Pages. It incorporates HTML, SCSS, JavaScript, and images from GDS's Tech Docs Template, reworked to use Jekyll instead of Middleman.
All commits must be signed.
Information about contributing is provided here.
Information about setting up the build environment, and building content, is here.
You must set up the build environment to work with this repository.
To preview the site locally, after it is built, we need to use the terminal.
Install Ruby and Bundler, preferably with a Ruby version manager. Ruby version 2.7.3 is known to work well for local builds.
Once you have Ruby and Bundler set up, you can install this project's
dependencies by running the following in the docs
directory:
bundle install
The correct way to make changes is by editing the appropriate DITA XML files in the dita
directory. The builder.ant
script in the buildUtils
directory is used to create output content from the DITA source.
Any changes you want to suggest must be created in a branch, and submitted using a pull request when you want them to be reviewed and potentially published.
The tolerated way of making changes is by editing an existing Markdown file in the docs
directory. Be aware that changes made in the docs
directory are non-persistent, and are overwritten by the build process.
For more information about contributing content, see this description. Please ask if you have questions or would like help - issues are the best way to contact the content team.
We can preview content in the docs
directory, locally, by running this command:
bundle exec jekyll serve --watch
This will create a local web server, probably at http://127.0.0.1:4000
(look for the Server address:
line). This is only accessible on our
own computer, and won't be accessible to anyone else. It's also set up
to automatically update (thanks to --watch
) when we make changes to
the working Markdown files.
Because we're using GitHub Pages, any changes merged into the main
branch docs
directory will be published automatically. Every change should be reviewed
in a pull request, no matter how minor, and we've enabled branch protection to enforce this.
Every time a build run takes place, a working copy of the Intranet material is placed in the intranet folder.
Whenever an Intranet publication is required, the following process is used:
git tag -a YYYYMMDD -m "Intranet Snapshot YYYYMMDD"
The YYYYMMDD is the date of the snapshot. For example:
git tag -a 20210205 -m "Intranet Snapshot 20210205"
git push origin YYYYMMDD
For example:
git push origin 20210205
.zip
file containing the contents of the intranet
folder.To get a list of the annotated tags, use the command:
git tag
encrypted
folderOccasionally, there might be times when we need to work with material that is
sensitive in some way.
A good example is material that might be marked as OFFICIAL-SENSITIVE
,
such as personal information.
Such material is still OFFICIAL
,
but has the additional handling indicator ('SENSITIVE
') to show that this
material should be treated with extra care.
A good rule of thumb is that the information is 'need to know',
and should not be shared in public.
This material can be stored in the encrypted
folder,
where it is protected (encrypted) using the
git-crypt
tools.
The tools are approved for use by the MoJ.
Use of git-crypt
is normally for
repositories with only a small number of encrypted files;
the majority of files in the repository are plain text.
For this MoJ security-guidance repository,
it is expected that encrypted files will be exceptional,
rather than a common or frequent occurrence.
As a working measure,
the number of encrypted source files should not exceed 1% of the number of
source files in the repository.
If the 1% value is exceeded,
the use of git-crypt
will be reviewed.
You do not need to have git-crypt
available to work with the majority
of materials in this repository.
If you don't have git-crypt
,
the files in the encrypted
directory are protected;
you can see they exist,
but you won't be able to see or work with the contents of the file.
For the vast majority of tasks,
there is no need to access or view the contents of the encrypted
folder.
If you really feel there is a need to access the materials, do the following:
git-crypt
.git-crypt
on your system.encrypted
folder.encrypted
folder, and providing a very good business justification.