diff --git a/docs/index.rst b/docs/index.rst index 4344ecf..c8954a1 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,10 +3,177 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to awsfindingsmanagerlib's documentation! -================================================= +awsfindingsmanagerlib +********************* -Contents: +*Focus on what matters.* + +Automated scanning and finding consolidation is a cornerstone in evaluating your security posture. +AWS Security Hub is the native solution to preform this in job in AWS. +As with any scanning and reporting tool, the amount of findings it generates can be overwhelming at first. +Also, you may find that some findings are not relevant or have less urgency to fix in your specific situation. + +**awsfindingsmanagerlib** suppresses findings based on a ruleset you define. + +Quickstart +========== + +Install with your favorite Python package manager like:: + + pip install awsfindingsmanagerlib + +Define what you don't want to bother you anymore, for example: + +.. code-block:: yaml + + Rules: + - note: Mom said it's okay to ignore + action: SUPPRESSED + match_on: + security_control_id: GuardDuty.1 + +Save and serve your ruleset, for example locally as ``suppressions.yaml`` and with ``python3 -m http.server``. +(More logical/advanced ways of getting your suppressions to your findings manager are covered later.) +Then you should be able to run the following Python code; +provided your AWS credentials allow +``ec2:DescribeRegions``, ``securityhub:GetFindings`` and ``securityhub:BatchUpdateFindings``. + +.. code-block:: python + + from awsfindingsmanagerlib import FindingsManager, Http + + http_backend = Http('http://localhost:8000/suppressions.yaml') + + findings_manager = FindingsManager('eu-west-1') + findings_manager.register_rules(http_backend.get_rules()) + findings_manager.suppress_matching_findings() + +And zip 🤐 all noise is silenced. + +Why use awsfindingsmanagerlib? +============================== + +You may wonder what justifies using a dedicated lib to suppress findings. +You could have just as easily, maybe even more easily clicked suppress in the console, right? +Yes, BUT, actually, multiple buts. +Let's sum up the advantages of using awsfindingsmanagerlib from the skeptic's perspective. + +"I can just do this in the AWS console" +--------------------------------------- + +Well, that will be a tedious amount of clicking for a lot false positives, while you could have just written: + +.. code-block:: yaml + + Rules: + - note: My dev instance + action: SUPPRESSED + match_on: + resource_ids: + - arn:aws:ec2:eu-central-1:1234567890:instance/i-1234567890 + +Maybe, better yet: + +.. code-block:: yaml + + Rules: + - note: dev resources by tag + action: SUPPRESSED + match_on: + tags: + - key: env + value: dev + - note: dev resources by name + action: SUPPRESSED + match_on: + resource_ids: + - '*-dev$' # yes, we support regex + +Add this point you might almost get scared of being too suppressive. +Don't panic: + +.. code-block:: yaml + + Rules: + - note: We'll make this one exception, especially for you two then + action: SUPPRESSED + match_on: + security_control_id: 'IAM.3' + resource_ids: + - '^arn:aws:iam::1234567890:user/lazyperson1$' + - '^arn:aws:iam::1234567890:user/lazyperson2$' + +As you can see, suppressions can now be expressed in a more general, meaningful, dare-we-say-Pythonic way. +Moreover, you can apply your suppressions over all your AWS accounts with this tool with little effort. +Control ids are the same in every AWS account and you can express you resources with tags and regex. +This way, your suppressions become portable through your whole environment. + +The generality makes it possible to apply the suppressions even in your audit account, despite differing AWS account ids. +This way you can get a truly good overview without clutter from false positives. + +"I don't have that many findings to suppress" +--------------------------------------------- + +Even if you don't have many false positives in your environment, findings are only saved for 90 days. +After that time your suppressions are gone with them. +Most checks immediately generate a new finding then. +Re-suppressing these findings each time manually is error-prone and can eventually amount to a lot of work. + +To reduce errors further, we recommend storing your suppressions file in a VCS and suppressing in full automation. +(See below for our :ref:`reference implementation `.) + +"I use Splunk, Datadog, OpenSearch, AWS Security Hub Automations etc., instead" +------------------------------------------------------------------------------- + +The tools above can be divided in AWS Security Hub Automations and third-party tooling. +We think this lib provides something both categories do not offer. +First, we'll cover third-party tooling. + +It's generally a good idea to handle an event as close to the source as possible. +Therefore, we think it's better to suppress findings in AWS Security Hub instead of filtering in third-party tooling. +There is certainly something to be said for creating aggregation views in such tools, especially in a multi-cloud environment. +Still, you will more easily create a comprehensive view in any third-party tool if only the relevant data is sent there. +On top of that, it will save save you money from storage and increase your search speed. + +AWS Security Hub Automations is AWS' native solution for exactly the same job as this lib. +However, we think this lib provides usability features that make it a better choice. +Most importantly, this lib allows you to suppress based on multiple combinations of property values in one rule. +As in the example above, you can suppress a single check for multiple resources. +In Automations this would require multiple rules. + +Maybe a counter-intuitive strong point of this lib is that the resource matching supports regex. +Regex has its obvious readability issues, but it's far more flexible than Automations' filter: prefix/suffix. +Imagine want to suppress for a resource collection in your dev/test accounts. +With regex you can write something like: +`arn:aws:lambda:eu-central-1:(1234567890|2345678901):function:(client-a|client-b|client-c)` +With Automations you would have to write multiple rules for this. + +Observant readers will realize that up until now we only listed readability issues. +We think that readability is a big thing, especially because suppressions should be regularly reviewed. +Those reviews are likely carried out by someone else than the one who wrote them. + +Not convinced by readability alone? +Automations has a 100 rule limit. +That limit fills up quickly if you have to a rule for every permutation without support for regex and multiple property combination. +In an organization's audit account it's probably impossible to work with. + +Finally, this lib can suppress findings from the past if you want. +Automations can only work with findings in the future. +With this lib you don't have to wait the 90 days findings retention time before your dashboard stops blaring at you. + +.. _reference-implementation: + +"Alright, I want this, why is there still more text on this page?" +------------------------------------------------------------------ + +Well, this is 'just' a lib. +While it provides all the magic you want, why do the standard infra work yourself? +We have a standard implementation of suppressing with this lib available in Terraform +`here `_. +On top of that, it provides some integrations for automatic alerting and ticketing. + +Contents +======== .. toctree:: :maxdepth: 2 @@ -20,9 +187,8 @@ Contents: history Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`modindex` * :ref:`search` -