The policy file is a JSON object and, as such is subject to manipulation. In order to balance usability (e.g. being able to read the file, update the policy, translate the values to boilerplate code) with security, we included some means to be able to identify changes to the policy through the use of the integrity flag
Upon creation or change to either security.json or security.js, _spartan runs the shasum program locally against the newly generated files and returns a SHA-384 hash of the files to standard output.
There are two ways to see the hash value of the policy file:
|Type This||Returns this (Example)|
||SHA-384 hash of ./security.json: WdocEYtCN5uF7prDM5B6Sr3RMxnXj7o5hxG4SbSHb5DGfUIVcV0BcPQc3sQTxRyQ
SHA-384 hash of ./security.js: rACLXtgnmgUibT3haAwHrEFij+DPFLwGeOJvhKypvqb+31HgeR0zXIS9G6veI7vi
||SHA-384 hash of /[absolute path to your project]/security.json: QfeANx/4pCOyTrJTn5b28oe1iYInTL7f1cjcsP1WvRXo4OjDxggfD9MX6bw8jDde
SHA-384 hash of /absolute path to your project]/security.js: OTFZqE0RiSPl22PvDgHLSyfzToSrPzT4m68t1Z7qj6PTJlvopkaiPSpWwV92cuSU
_spartan offers out of the box support for openssl and shasum. You can specify which hash tool you want to use for this purpose by running
_spartan -i [openssl | shasum]. If nothing is specified, _spartan defaults to using shasum
One of the immediate uses of this value is in your CI/CD pipeline. For example, you could write a test that hashes the file and compares it to the hash value generated with _spartan (assumes that you stored this value somewhere). If the values are different, then you know that the file has been tampered with. The test should fail and you can reject the PR, preventing it from being ingested into the main code base.
If you have any kind of downstream auditing system (like a file integrity monitoring service), you can track changes to the policy by ingesting the hash value; if the audit system pulls (rather than polls) changes as they occur, you’ll also have a timestamp of when the file was changed.
Additionally, you should consider posting the hash value in whatever code repository your project will be stored in. In this way, developers who decide to fork or clone the project can immediately hash the policy file and validate the integrity of the policy is still intact.
As of the time of this writing, _spartan does not add a randomly generated salt prior to hashing the file, so take the hash with a grain of…salt. We’ve already created an issue in github to fix this. You can keep track of progress here
Each policy includes a unique identifier known as the ‘policy ID’
When you create a new policy, _spartan automatically generates and appends a 32-digit alphanumeric value to the policy. It looks like this:
How does it relate to integrity?
One way to use this value is in policy generation. If you wanted to see the impact of changing security settings without completely overwriting your existing policy, you could do this by running
_spartan --no-overwrite. The result of this will be a new policy (with a new ID) which can be manipulated and updated without modifying your existing policy. When you’re ready, rename this file as ‘security.json’ and run the
--force command to regenerate the boilerplate code like this:
# at command prompt $ _spartan --no-overwrite # normal interview questions $ ls package.json security/ security.js security-59031f2d.json security.json # modify new file 'security-59031f2d.json' as needed $ mv security-59031f2d.json security.json # regenerate boilerplate code $ _spartan --force
_spartan will only generate the boilerplate code for the file named ‘security.json’ in your project root directory.