From e5284cb8df66f9a10cd378cfeca7895ef44a1add Mon Sep 17 00:00:00 2001 From: Samriddhi Singh Date: Tue, 16 Jul 2024 13:09:55 +0530 Subject: [PATCH 1/2] Add a getting started guide in README.md --- README.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) diff --git a/README.md b/README.md index 562fd53..1437f2e 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ Tirith scans declarative Infrastructure as Code (IaC) configurations like Terraf - [StackGuardian Workflow Policy](#stackguardian-workflow-policy-using-sg-workflow-provider) - [JSON](#json) - [Kubernetes](#kubernetes) +- [Getting Started](#getting-started) - [Want to contribute?](#want-to-contribute) - [Getting an issue assigned](#getting-an-issue-assigned) - [A bug report](#a-bug-report) @@ -1110,6 +1111,146 @@ JSON Output: ``` twine upload --repository-url https://test.pypi.org/legacy/ dist/* ``` --> +## Getting Started + +create two files, one for input.json one for +policy.json. + +**input.json** + +```json +{ + "path": "/stackguardian/wfgrps/test", + "verb": "POST", + "meta": { + "epoch": 1718860398, + "User-Agent": { + "name": "User-Agent", + "value": "PostmanRuntime/7.26.8" + } + } +} +``` + +**policy.json** + +```json +{ + "meta": { + "version": "v1", + "required_provider": "stackguardian/json" + }, + "evaluators": [ + { + "id": "can_post", + "provider_args": { + "operation_type": "get_value", + "key_path": "verb" + }, + "condition": { + "type": "Equals", + "value": "POST" + } + }, + { + "id": "wfgrps_path", + "provider_args": { + "operation_type": "get_value", + "key_path": "path" + }, + "condition": { + "type": "RegexMatch", + "value": "/stackguardian/wfgrps/test.*" + } + }, + { + "id": "epoch_less_than_8th_july_2024", + "provider_args": { + "operation_type": "get_value", + "key_path": "meta.epoch" + }, + "condition": { + "type": "LessThan", + "value": 1720415598 + } + } + ], + "eval_expression": "can_post && wfgrps_path && epoch_less_than_8th_july_2024" +} +``` + +### Evaluating the policy against the input + +To evaluate the policy against the input, run the following command: + +```sh +tirith -input-path input.json -policy-path policy.json +``` + +Explanation: + +- **tirith**: + - This is the command to run the Tirith program, which is part of + the StackGuardian Policy Framework. + +- **-input-path input.json**: + - The -input-path option specifies the path to the input file. + - input.json is the file that contains the input data to be + scanned by Tirith. + +- **-policy-path policy.json**: + - The -policy-path option specifies the path to the policy file. + - policy.json is the file that contains the policies (rules) + defined in Tirith\'s policy as code. + +It should print: +``` +Check: can_post + PASSED + Results: + 1. PASSED: POST is equal to POST + +Check: wfgrps_path + PASSED + Results: + 1. PASSED: /stackguardian/wfgrps/test matches regex pattern /stackguardian/wfgrps/test.* + +Check: epoch_less_than_8th_july_2024 + PASSED + Results: + 1. PASSED: 1718860398 is less than 1720415598 + +Passed: 3 Failed: 0 Skipped: 0 + +Final expression used: +-> can_post && wfgrps_path && epoch_less_than_8th_july_2024 +✔ Passed final evaluator +``` + + +### Error tolerance + +What if sometimes one or more keys inside the input file are not found? +Let's try to delete the **verb** key inside the **input.json** and see +what happens when we try to run the evaluation again using the same +command above. + +It should fail the evaluation. + +What if we, as a user, want the evaluator to "skips" itself (don't +include the result to the final evaluator) when a particular key is not +found? + +This is when **error tolerance** can be helpful. + +A provider can raise an error and the error itself has a **severity** +value. (see Appendix). In this case the JSON provider raises an error of +severity value 2 when the `get_value` operation can't find the JSON +path inside the input. + +By setting the **error_tolerance** value to 2 or more inside the +**condition** key in the evaluator, it will mark the evaluator as Skipped instead of Failed. + ## Want to contribute? From a3e16d8c25bd02e2b5283665040b49d6b225eeeb Mon Sep 17 00:00:00 2001 From: Samriddhi Singh Date: Wed, 24 Jul 2024 16:42:54 +0530 Subject: [PATCH 2/2] Add description of getting started activity, and some minor fixes --- README.md | 39 ++++++++------------------------------- 1 file changed, 8 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 1437f2e..42d2fc0 100644 --- a/README.md +++ b/README.md @@ -1113,8 +1113,9 @@ JSON Output: ``` --> ## Getting Started -create two files, one for input.json one for -policy.json. +This is a short getting started guide for Tirith. We will take a look on how we can use Tirith to guardrail a JSON input. + +Create two files, one for input.json one for policy.json. **input.json** @@ -1189,17 +1190,17 @@ tirith -input-path input.json -policy-path policy.json Explanation: -- **tirith**: +- `tirith`: - This is the command to run the Tirith program, which is part of the StackGuardian Policy Framework. -- **-input-path input.json**: - - The -input-path option specifies the path to the input file. +- `-input-path input.json`: + - The `-input-path` option specifies the path to the input file. - input.json is the file that contains the input data to be scanned by Tirith. -- **-policy-path policy.json**: - - The -policy-path option specifies the path to the policy file. +- `-policy-path policy.json`: + - The `-policy-path option` specifies the path to the policy file. - policy.json is the file that contains the policies (rules) defined in Tirith\'s policy as code. @@ -1228,30 +1229,6 @@ Final expression used: ``` -### Error tolerance - -What if sometimes one or more keys inside the input file are not found? -Let's try to delete the **verb** key inside the **input.json** and see -what happens when we try to run the evaluation again using the same -command above. - -It should fail the evaluation. - -What if we, as a user, want the evaluator to "skips" itself (don't -include the result to the final evaluator) when a particular key is not -found? - -This is when **error tolerance** can be helpful. - -A provider can raise an error and the error itself has a **severity** -value. (see Appendix). In this case the JSON provider raises an error of -severity value 2 when the `get_value` operation can't find the JSON -path inside the input. - -By setting the **error_tolerance** value to 2 or more inside the -**condition** key in the evaluator, it will mark the evaluator as Skipped instead of Failed. - - ## Want to contribute? If you're interested, please email us at team[at]stackguardian.io or get started by reading the [contributing.md](./CONTRIBUTING.md).