Skip to content

Content changer improvements and Stale Reference Updates - #2192

Merged
patel-bhavin merged 59 commits into
developfrom
content_changer_improvements
Jun 29, 2022
Merged

patel-bhavin merged 59 commits into
developfrom
content_changer_improvements

Conversation

@pyth0n1c

@pyth0n1c pyth0n1c commented May 11, 2022 •

Copy link
Copy Markdown
Collaborator

This is a significant PR with a group of updates that seeks to improve content_ctl performance and update the references linked in our detections, stories, playbooks, etc.

Updates to content_changer
When speaking with some customers, they indicated that they are largely following the structure of our YMLs. However, there are a number of fields that we use (for construction of things like analytic stories, attack mapping frameworks, etc) that are not included in their detections. content_changer now enumerates all the available transforms (and will auto-update if we add additional transforms) when passing --help at the command line. An "all" function has also been added which will apply all the transforms and add default values if they are missing. This allows a detection which is missing a number of fields to be updated so that it can process successfully.

Speedup for content_ctl validate and generate CveEnrichment and AttackEnrichment
content_ctl validate and generate functions perform a large number of REST API calls when processing our content. However, the endpoints these reach out to can be slow and a single run of content_ctl may take 5 minutes (or longer if the endpoints are particularly slow). There are two optimizations in place here:

  • Calls to CVE Enrichment are always cached in memory but are not written to disk for persistence. This means that subsequent calls on the same CVE return instantly, saving time.
    TEST COMMAND (no change from current command line):
    python contentctl.py --path . validate --product ESCU

  • The command line argument --cached_and_offline will force attack_enrichment to use the cached mitre_enrichment located at lookups/mitre_enrichment.csv. It will also Cache calls to CveEnrichment to disk at lookups/CVE_CACHE.db. Using this option means that after the first run of the tool, subsequent calls return in less than 10 seconds, speeding up development and troubleshooting significantly.
    TEST COMMAND (try running twice to observe the difference):
    python contentctl.py --path . --cached_and_offline validate --product ESCU
    python contentctl.py --path . --cached_and_offline validate --product ESCU
    python contentctl.py --path . --cached_and_offline generate --product SSA -o dist/ssa
    python contentctl.py --path . --cached_and_offline generate --product SSA -o dist/ssa

content_ctl Progress Monitoring
Previously, content_ctl ran for several minutes and did not provide progress updates. Now, the tool will tell the user what step of the process it is on with an approximate progress meter (0-100%) for validate and generate. Run any of the other commands in this description to see this functionality.

content_ctl Skip Enrichment Except for Tagged Releases
By default, content_ctl will add a significant amount of enrichment (related to referenced CVEs) when running validate and generate. While this is great when generating a release version of the app, it significantly slows down testing and results in a large number of API calls that need to be made. In a non-tagged CI/CD job, the --skip_enrichment flag will be passed to calls to content_ctl, resulting in much faster workflows. However, Enrichment will still run for Tagged Workflows. This could result in a a package passing the pre-tagged CI/CD workflow but failing the Tagged Workflow due to an error in enrichment (for example, a CVE is referenced that does not exist).

Updates to broken or outdated reference links
We use thousands of reference links in security_content and it's important to keep all of these up-to-date. For any variety of reasons, the links can fail or result in redirects. To make finding these issues easier, the argument --check_references (for validate) can be used to examine all references in detections, stories, baselines, etc. The tool examines and prints non-200 return codes and the files that contain them so that the user may troubleshoot them. A very large number of our links had redirects (due to naming scheme changes or company acquisitions) and some sites were no longer accessible (even after searching for the text of the page in Google). In that case, those sites were replaced with Internet Archive links.
About 150 of our references have been updated with the help of this tool - it will be scheduled in the CI to run nightly or weekly so that we can always keep our links fresh.
if --cached_and_offline is used with --check_references, the on subsequent runs of the tool only bad references will be re-checked. Good ones will still be assumed as good.
TEST COMMAND (try running twice to observe the difference):
python contentctl.py --path . --cached_and_offline validate --product ESCU --check_references
python contentctl.py --path . --cached_and_offline validate --product ESCU --check_references

pyth0n1c added 23 commits April 29, 2022 13:31
that content_changer can make.  This list of actions
will be dynamically updated base on the names of
the functions added in content_changer.py!
…es. The help statement for content_changer in content_ctl now dynamically lists the transforms that can be performed on detections. In addition, a redundant transfrom was removed.
…ctl. This means that developers can much more rapidly test new builds without waiting on slow API end points \(taking build and validate job from upwards of 10 minutes to a few seconds\). It also means that the tool can be used in completely offline, secure environments that do not mirror the required HTTP endpoints.
…ds up verification of URLS. Also, got the cache working and the force cache argument passed all the way through to the detection builder. Please note that this will take much longer to run the first time, because the cache has not been populated. Subsequent runs will be slower. If data exists in this cache, it is NOT updated and will become stale if the web resource is updated. This is only suitable for development purposes and offline environments.
…ning HTTP Status 301 - resource moved. For example, this includes a large number of fireeye reports, which are now under mandiant, cobaltstrike info, and microsoft links.
…he reference URLs in detections at scale. Also, fixed a few more HTTP Status Code 301 references in the tests folder.
…ed the number of threads that run and tweaked the timeout time.
…rences that fail validation cannot be easily validated by requests, due to website requirements, or sometimes return errors or take a long time to load. Becuase they usually work, we will leave them as-is.
…of caching, similar to functools caching, but keeps additional metrics suitable for dumping when all validation has completed.
…t we have now broken these out into a more robust class link_validator.py
investigations, and stories. Still some testing to
be done.
performed successful tests against
all Stories, Playbooks, Baselines,
Detections, and Investigations.
Also tested when the check_references
or --no-check_references flags are passed
successfully!
from contentctl to the builders.
…icators to the steps of the factory so that users have feedback on what is going on when contentctl is running. This is helpful since it can run for an extended period of time, especially on a slower or high latency connection, when links are being validated, or when caching is not enabled.
…out at the end after all links have been checked instead of when the tool is running, making it easier to read. Files that referernce the link are also included.
…actory if they are not needed - only generate the one or ones that are required. Also, provide status printouts for the AttackEnrichment so that the user can monitor progress and be sure something is happening.
…_offline argument. This means that if a link returns successfully and you run the tool again, the link won't be checked again. However, this means that if that cache sticks around for a long time, the link may actually stop returning but we won't continue checking it. Still, this makes it significantly easier to quickly find broken links, fix the broken links, and then run the tool again in a short period of time, only re-checking the broken links that have been fixed. This makes repairing and checking broken links a must faster workflow.
…o shelve.Shelf for Reference cache. The interface is nearly identical, but it results in much cleaner code. We will likely do the same in the next commit for CVE cache.
…ell. This also replaced plain dict functionality and simplified the code.
@pyth0n1c pyth0n1c added the WIP DO NOT MERGE Work in Progress label May 11, 2022
@auto-assign
auto-assign Bot requested a review from patel-bhavin May 11, 2022 21:52
pyth0n1c added 5 commits May 13, 2022 07:51
creation of App Enrichment, CVE, and
link validator caches.  Made sure to close
CVE and App Enrichment caches after
they are opened and accessed instead of
relying on Python to close them for us
when their reference count is zero.
Also tested to ensure that if a previous
validate and generate succeeded, it
can be run again with no internet access!
This is perfect not just for performance
reasons, but offline/disconnected
environments.
@josehelps josehelps closed this Jun 10, 2022
@josehelps josehelps reopened this Jun 10, 2022
pyth0n1c added 9 commits June 22, 2022 13:44
contentctl tool.  This can save a huge amount
of time when generating an app.  Also
added a progress meter when the documentation
is being generated. Finally, correctly initialized
the default values of some class member fields
in order to get all the contentctl steps working.
workflow, collapsing several jobs into
one.
after updating job names
the --skip_enrichment argument
to content_ctl based on whether
or not we are running CI/CD workflow
on a tagged release
generate.  This passes initial
testing using nektos act on
my own system!
…flict. this was making it impossible to merge the PR in the GitHub Interface.
@pyth0n1c pyth0n1c added WIP DO NOT MERGE Work in Progress and removed WIP DO NOT MERGE Work in Progress labels Jun 23, 2022
pyth0n1c added 2 commits June 23, 2022 15:18
to use the latest contentctl from develop
as well as skip enrichment.
lines to be jumbled together.
@pyth0n1c pyth0n1c removed the WIP DO NOT MERGE Work in Progress label Jun 23, 2022
@patel-bhavin
patel-bhavin merged commit d060bfd into develop Jun 29, 2022
@delete-merged-branch
delete-merged-branch Bot deleted the content_changer_improvements branch June 29, 2022 19:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants