POLICY INTEGRITY

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 integrity results

HOW IT WORKS

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.

USAGE

There are two ways to see the hash value of the policy file:

Type This Returns this (Example)
_spartan -i SHA-384 hash of ./security.json: WdocEYtCN5uF7prDM5B6Sr3RMxnXj7o5hxG4SbSHb5DGfUIVcV0BcPQc3sQTxRyQ

SHA-384 hash of ./security.js: rACLXtgnmgUibT3haAwHrEFij+DPFLwGeOJvhKypvqb+31HgeR0zXIS9G6veI7vi
_spartan [policy create methods] 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

OK, SO WHAT TO DO WITH THIS?

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

POLICY ID

Each policy includes a unique identifier known as the ‘policy ID’

HOW IT WORKS

When you create a new policy, _spartan automatically generates and appends a 32-digit alphanumeric value to the policy. It looks like this:

"policyId": "2ad6d6804251e4299fe9c8f450a30a5c"

How does it relate to integrity?

  • This value is completely unique. No two policies will have the same ID. A change in policy ID is effectively treated as a different policy.
    • _spartan completely overwrites the policy ID on ‘create’ actions
    • On ‘no-overwrite’ actions, _spartan compares the policy ID in security.json to the newly generated ID to ensure there are no collisions (matches)
  • On policy updates the ID will not change, however the hash value will change.

OK, SO WHAT TO DO WITH THIS?

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.