open-quantum-safe#1706 scorecard - add docs & template file for requi…

…rements

Signed-off-by: Nigel Jones <[email protected]>

.github/workflows/requirements.in

@@ -0,0 +1,8 @@
+colorama==0.4.6
+execnet==2.1.1
+iniconfig==2.0.0
+packaging==24.0
+pluggy==1.4.0
+pytest==8.1.1
+pytest-xdist==3.5.0
+pyyaml==6.0.1

docs/PROCEDURES.md

@@ -0,0 +1,69 @@
+# Additional procedures for code maintenance 
+
+## Managing pinned dependencies
+
+The OpenSSF, via the [scorecard](https://securityscorecards.dev/) project recommends that projects pin any
+dependencies they use:
+
+* to ensure reproducibility
+* to reduce the change for rogue dependency updates to compromise software
+
+It's important to note that this requires any changes to dependencies are properly reviews, and
+these changes, by design, should not be automatic in themselves, though automated tools may provide recommendations.
+
+### Python dependencies
+
+Python dependencies used in the build process should be pinned to a specific version to ensure reproducibility.
+
+This is done by:
+ * Using the `--require-hashes` option on any `pip install` command line
+ * Adding the required hash in the `requirements.txt`
+
+ Currently this is used withou `.github/workflows` but the same principle applies elsewhere.
+
+ To make this easier, a version of the `requirements.txt` without hashes has been saved as `requirements.in`. This is
+ to make maintenance easier, but it is not used at script execution time.
+
+ The `pip-compile` tool must be installed via the [pip-tools](https://pypi.org/project/pip-tools/) package.
+
+ To add a new, or changed dependency:
+ ```
+ pip-compile --generate-hashes --output-file=requirements.txt requirements.in
+ ```
+
+ This will update requirements.txt with the correct hashes.
+
+ Correction function should be verified, and then both `requirements.txt` and `requirements.in` checked in.
+
+### Github Actions
+
+All actions used in `.github/worfklows' should pin the exact version of the action they are using, for
+example a step such as:
+
+```yaml
+- name: Checkout code
+  uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # pin@v4
+```
+
+The exact hash specified after `@` is the git commit hash within the repo where the action is found.
+
+The [pin github action](https://github.com/mheap/pin-github-action) tool can be used to maintain these
+by, for example, running:
+
+```shell
+pin-github-action unix.yml
+```
+
+This will update the hashes with the latest version if no pinned value is set.
+
+For major updates, update the comment ie `pin@v4` to `pin@v5` and the tool will attempt to find the new hash.
+
+To help in explanation here's an example of a similar code fragment between tool executions:
+
+* Original entry is `uses: actions/checkout@v3`
+* run `pin-github-action unix.yml`
+* We now see `uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # pin@v3`
+* later we want to go to v4, so update the text to `uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # pin@v4`
+* Now run `pin-github-action unix.yml` to correct the sha
+* File now shows `uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # pin@v4`
+