github/kube-hunter
1
0
Fork 0
mirror of https://github.com/aquasecurity/kube-hunter.git synced 2026-08-23 22:26:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improved documentation (#201)

Browse Source
This commit is contained in:
michizhou
2019-10-23 11:16:49 +01:00
committed by Liz Rice
parent a8428a9445
commit d8037434a0
2 changed files with 22 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+5 -5
View File
@@ -1,4 +1,4 @@
Thank you for taking interest in contributing to kube-hunter !
Thank you for taking interest in contributing to kube-hunter!
## Issues
- Feel free to open issues for any reason as long as you make it clear if this issue is about a bug/feature/hunter/question/comment.
@@ -10,7 +10,7 @@ Thank you for taking interest in contributing to kube-hunter !
1. Every Pull Request should have an associated Issue unless you are fixing a trivial documentation issue.
1. Your PR is more likely to be accepted if it focuses on just one change.
1. Describe what the PR does. There's no convention enforced, but please try to be concise and descriptive. Treat the PR description as a commit message. Titles that starts with "fix"/"add"/"improve"/"remove" are good examples.
1. Describe what the PR does. There's no convention enforced, but please try to be concise and descriptive. Treat the PR description as a commit message. Titles that start with "fix"/"add"/"improve"/"remove" are good examples.
1. Please add the associated Issue in the PR description.
1. There's no need to add or tag reviewers.
1. If a reviewer commented on your code or asked for changes, please remember to mark the discussion as resolved after you address it. PRs with unresolved issues should not be merged (even if the comment is unclear or requires no action from your side).
@@ -19,8 +19,8 @@ Thank you for taking interest in contributing to kube-hunter !
## Hunters
If you are contributing a new hunter:
1. When you open an issue to present the hunter, please specify which `Vulnerability` classes you plan to add.
1. A maintainer will assign each `Vulnerability` a VID for you to include in your hunter code.
If you are contributing a new Hunter:
1. When you open an issue to present the Hunter, please specify which `Vulnerability` classes you plan to add.
1. A maintainer will assign each `Vulnerability` a VID for you to include in your Hunter code.
1. Please add a KB article to `/docs/kb/` explaining the vulnerability and suggesting remediation steps. Look at other articles for examples.
1. Please adhere to the following types convention: Use `Hunter` class to report vulnerabilities, `ActiveHunter` if your Hunter might change the state of the cluster, and `Discovery` for scanning the cluster (all are descendants of `HunterBase`). Also, use the `Vulnerability` class to report findings, and `Service` to report a discovery to be used by a hunter (both are descendants of `Event`, refrain from using `Event` directly).
src/README.md
+17 -18
View File
@@ -32,7 +32,7 @@ Example:
@handler.subscribe(OpenPortEvent, predicate=lambda event: event.port == 30000)
class KubeDashboardDiscovery(Hunter):
"""Dashboard Discovery
Explanation about what the hunter does
Explanation about what the Hunter does
"""
def __init__(self, event):
self.event = event
@@ -40,8 +40,8 @@ class KubeDashboardDiscovery(Hunter):
pass
~~~
Kube-hunter's core module triggers your Hunter when the event you have subscribed it to occurs.
in this example, we subscribe the Hunter, `KubeDashboardDiscovery`, to an `OpenPortEvent`, with a predicate that checks the open port (of the event) is 30000.
`Convention:` The first line of the comment describing the hunter is the visible name, the other lines are the explanation.
In this example, we subscribe the Hunter, `KubeDashboardDiscovery`, to an `OpenPortEvent`, with a predicate that checks the open port (of the event) is 30000.
`Convention:` The first line of the comment describing the Hunter is the visible name, the other lines are the explanation.
##### ActiveHunter
@@ -58,7 +58,7 @@ class ProveSomeVulnerability(ActiveHunter):
* Every hunter, needs to save its given event from the `__init__` in it's attributes.
* When subscribing to an event, if a `predicate` is specified, it will be called with the event itself, pre-trigger.
* When inheriting from `Hunter` or `ActiveHunter` you can use the `self.publish_event(event)`.
`event` is an **initialized** event object
`event` is an **initialized** event object.
-----------------------
@@ -66,13 +66,13 @@ class ProveSomeVulnerability(ActiveHunter):
The first step is to create a new file in the `hunting` or the `discovery` folder.
_The file's (module's) content is imported automatically"_
`Convention:` Hunters which discover a new service should be placed under the `discovery` folder.
`Convention:` Hunters which discover a new vulnerability, should be placed under the `hunting` folder.
`Convention:` Hunters which use vulnerabilities, should be placed under the `hunting` folder and should implement the ActiveHunter base class.
`Convention:` Hunters which discover a new vulnerability should be placed under the `hunting` folder.
`Convention:` Hunters which use vulnerabilities should be placed under the `hunting` folder and should implement the ActiveHunter base class.
The second step is to determine what events your Hunter will subscribe to, and from where you can get them.
`Convention:` Events should be declared in their corresponding module. for example, a KubeDashboardEvent event is declared in the dashboard discovery module.
`Convention:` Events should be declared in their corresponding module. For example, a KubeDashboardEvent event is declared in the dashboard discovery module.
`Note:` An hunter located under the `discovery` folder should not import any modules located under the `hunting` folder
`Note:` A Hunter located under the `discovery` folder should not import any modules located under the `hunting` folder
in order to prevent circular dependency bug.
Following the above example, let's figure out the imports:
@@ -118,7 +118,7 @@ relative import: `...core.types`
## Creating Events
As discussed above, we know there are a lot of different types of events that can be created. but at the end, they all need to inherit from the base class `Event`
let's see some examples of creating different types of events:
Let's see some examples of creating different types of events:
### Vulnerability
```python
class ExposedMasterCN(Vulnerability, Event):
@@ -135,8 +135,8 @@ class OpenKubeDns(Service, Event):
def __init__(self):
Service.__init__(self, name="Kube-DNS")
```
`Notice:` Every type of event, should have an explanation in exactly the form shown above, that explanation will eventually be used when the report is made.
`Notice:` You can add any attribute to the event you create as needed, the examples shown above are the minimum implementation that needs to be made
`Notice:` Every type of event should have an explanation in exactly the form shown above (that explanation will eventually be used when the report is made).
`Notice:` You can add any attribute to the event you create as needed. The examples shown above are the minimum implementation that needs to be made.
-----------------------
## Events
@@ -173,8 +173,7 @@ class SslHunter(Hunter):
def execute(self):
do_magic(self.event.certificate)
```
Let's say we now want to do something with the hostname from the certificate from. In the event tree, we can check if the host attribute was assigned to our event previously, by directly accessing `event.host`. If it has not been specified from some reason, the value is `None`.
So this is sufficient for our example:
Let's say we now want to do something with the hostname from the certificate. In the event tree, we can check if the host attribute was assigned to our event previously, by directly accessing `event.host`. If it has not been specified for some reason, the value is `None`. So this is sufficient for our example:
```python
...
def execute(self):
@@ -185,12 +184,12 @@ def execute(self):
If another Hunter subscribes to the events that this Hunter publishes, it can access the `event.certificate`.
## Proving Vulnerabilities
The process of proving vulnerabilities is the base concept of the Active Hunting.
The process of proving vulnerabilities is the base concept of Active Hunting.
To prove a vulnerability, create an `ActiveHunter` that is subscribed to the vulnerability, and inside of the `execute`, specify the `evidence` attribute of the event.
*Note that you can specify the 'evidence' attribute without active hunting*
## Filtering Events
A filter can change an event's attribute or remove it completely before it gets published to hunters.
A filter can change an event's attribute or remove it completely before it gets published to Hunters.
To create a filter:
* create a class that inherits from `EventFilterBase` (from `src.core.events.types`)
@@ -221,8 +220,8 @@ class LocalHostFilter(EventFilterBase):
return self.event
```
The following filter will filter out any Service found on a localhost IP. Those Services will not get published to Kube-Hunter's Queue.
That means other hunters that are subscribed to this Service will not get triggered.
That opens up a wide variety of possible operations, as this not only can __filter out__ events, but you can actually __change event's attributes__, for example:
That means other Hunters that are subscribed to this Service will not get triggered.
That opens up a wide variety of possible operations, as this not only can __filter out__ events, but you can actually __change event attributes__, for example:
```python
from src.core.events import handler
@@ -242,7 +241,7 @@ class CensorInformation(EventFilterBase):
```
This will censor all vulnerabilities which can disclose information about a cluster.
__Note: in filters, you should not change attributes in the event.previous, this will result in unexpected behaviour__
__Note: In filters, you should not change attributes in the event.previous. This will result in unexpected behaviour__.
## Tests
Although we haven't been rigorous about this in the past, please add tests to support your code changes. Tests are executed like this: