Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Add credentials collectors explanation pages #4240

Merged
merged 15 commits into from
Jul 19, 2024

Conversation

shreyamalviya
Copy link
Contributor

What does this PR do?

Fixes #4212

PR Checklist

  • Have you added an explanation of what your changes do and why you'd like to include them?
  • Is the TravisCI build passing?
  • Was the CHANGELOG.md updated to reflect the changes?
  • Was the documentation framework updated to reflect the changes?
  • Have you checked that you haven't introduced any duplicate code?

Testing Checklist

  • Added relevant unit tests?
  • Do all unit tests pass?
  • Do all end-to-end tests pass?
  • Any other testing performed?

    Tested by {Running the Monkey locally with relevant config/running Island/...}

  • If applicable, add screenshots or log transcripts of the feature working

Copy link

codecov bot commented Jul 11, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 77.07%. Comparing base (dd956f4) to head (85099ce).
Report is 1 commits behind head on develop.

Additional details and impacted files
@@           Coverage Diff            @@
##           develop    #4240   +/-   ##
========================================
  Coverage    77.07%   77.07%           
========================================
  Files          442      442           
  Lines        14135    14135           
  Branches        18       18           
========================================
  Hits         10895    10895           
  Misses        3240     3240           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@shreyamalviya shreyamalviya force-pushed the 4212-docs-credentials-collector-explanation branch from 185c1c9 to 9f82c72 Compare July 15, 2024 13:17
@shreyamalviya shreyamalviya marked this pull request as ready for review July 15, 2024 13:17
Copy link
Collaborator

@mssalvatore mssalvatore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all of these pages need more information. What is mimikatz? Why would we steal credentials from chrome? How likely are those credentials to be useful in propagation? What's the risk if and SSH key is stolen?

@shreyamalviya shreyamalviya force-pushed the 4212-docs-credentials-collector-explanation branch from 3fb3f21 to ef7c703 Compare July 16, 2024 13:12
@mssalvatore mssalvatore force-pushed the 4212-docs-credentials-collector-explanation branch from ef7c703 to e865dad Compare July 16, 2024 13:18
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks fantastic!

@mssalvatore mssalvatore force-pushed the 4212-docs-credentials-collector-explanation branch from 2427a2c to 13948cd Compare July 16, 2024 20:06
@mssalvatore
Copy link
Collaborator

mssalvatore commented Jul 16, 2024

I expanded the explanation of Credentials Collectors:

image

I have two seemingly conflicting goals for this:

  1. Provide context. More specifically, answer the question, "why steal credentials?" To that end, we also need to answer, "how are stolen credentials used?"
  2. Keep this page concise and focused.

There may be a little bit too much detail about exploiters here, but I think it's important for users to understand how the stolen credentials are used. I think the solution would be to provide this information under Self-propagating Agent (Issue #4215) and just say, "for information about how stolen credentials are used ... blah blah ... see Self-propagating Agent". Since that page isn't ready yet, I think we should leave this text here. I've left a note in #4215 to extract/repurpose this text as part of that issue.

Similarly, instead of explaining exploiters, I'd rather just use the term "Exploiter" and link to the relevant documentation, but the relevant documentation doesn't exist yet. I've also left a note in #4213.

Comment on lines +23 to +37
When an Infection Monkey Agent is started, it begins the reconnaissance phase
of its attack. The first step in this phase is to use all enabled credentials
collectors to steal credentials. Any stolen credentials are then sent to the
Monkey Island, where they become immediately available for any Agent to use.

After the reconnaissance phase, the Agent will begin the propagation phase and
attempt to compromise other hosts on the network. Exploiters are Infection
Monkey plugins that attempt to spread copies of the Agent throughout the
network. Some exploiters can use the credentials stolen by credentials
collectors to gain access to other systems on the network. First, the exploiter
will query the Monkey Island to retrieve credentials that were configured by
the user and any credentials that were stolen by credentials collectors. Next,
the exploiters will use the stolen credentials to attempt to authenticate with
a target system. If authentication is successful, the exploiter will execute
the Agent on the target system, spreading the infection throughout the network.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still unsure if we should go into this much detail. I suggest we have a separate page explaining the different phases of execution which we could link to wherever required (probably each plugin type's explanation?). This isn't something that's specific to credentials collectors so it doesn't feel right to me here.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it should be on separate pages, which is why I left notes in #4213 and #4215 to extract it. However, this is information users need to understand. It needs to be somewhere, and if we get interrupted in between now and when we complete #4213 and #4215, at least it's here.

shreyamalviya and others added 15 commits July 18, 2024 19:54
We'd like to put explanation on chapter pages. Reading large amounts of
text that is center justified feels strange. This change does not modify
the format of existing chapter pages. However, any <p> element after a
<h2> element on a chapter page will now be formatted consistently with
the rest of the documentation.
I wasn't able to find any links to information about "Windows Credential
Manager" during a cursory web search. Maybe such a thing exists, but
it's somewhat elusive. In addition, all of the descriptions (including
our own) about Mimikatz describe it retrieving credentials "from
memory." Therefore, this commit changes the description of the mimikatz
collector to improve its accuracy.
@mssalvatore mssalvatore force-pushed the 4212-docs-credentials-collector-explanation branch from 85099ce to bf74c8f Compare July 19, 2024 00:09
@mssalvatore mssalvatore merged commit 0d8a3e3 into develop Jul 19, 2024
1 check failed
@mssalvatore mssalvatore deleted the 4212-docs-credentials-collector-explanation branch July 19, 2024 00:32
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add credentials collectors explanation
2 participants