From b9ffaa85655f635ebb2aed974ff01d37f30df239 Mon Sep 17 00:00:00 2001 From: Alexandre Dulaunoy Date: Wed, 18 Mar 2026 18:05:52 +0100 Subject: [PATCH] docs: harmonize grammar and style across book --- CONTRIBUTING.md | 79 ++++++++++++++--------------- GLOSSARY.md | 8 +-- README.md | 13 +++-- SUMMARY.md | 25 +++++----- USAGE.md | 56 ++++++++++----------- book-convention/README.md | 11 +++-- connectors/README.md | 31 ++++++------ create-event-report/README.md | 56 ++++++++++----------- delegation/README.md | 93 +++++++++++++++++++---------------- extended-events/README.md | 4 +- get-your-instance/README.md | 26 +++++----- modules/README.md | 16 +++--- noticelists/README.md | 8 +-- pymisp/README.md | 24 ++++----- translation/README.md | 15 +++--- updating-python/README.md | 30 +++++------ user-personas/README.md | 56 ++++++++++----------- warninglists/README.md | 35 ++++++------- 18 files changed, 304 insertions(+), 282 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32f0271..3c8e9ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,73 +1,73 @@ # Contributing to MISP Book -Most of MISP's documentation pages are stored as plain text files in this dedicated misp-book repository. -MISP Book is generic documentation for MISP including usage, API documentation, best practices, and specific configuration settings. -The installation guides are held in the [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively. -By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of MISP documentation rather than relying solely on the web. +Most MISP documentation pages are stored as plain-text files in this dedicated misp-book repository. +MISP Book provides general documentation for MISP, including usage, API documentation, best practices, and configuration guidance. +Installation guides are maintained in the [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively. +By cloning this repository and pulling regularly, users can maintain an up-to-date offline copy of the documentation instead of relying solely on the web. -MISP book is generated in HTML, PDF, epub, and mobi using [Honkit](https://github.com/honkit/honkit), which is a framework to write documentation in Markdown format. -The documentation is regularly published on [misp-project.org](https://www.misp-project.org/) and [circl.lu website](https://www.circl.lu/doc/misp/). +MISP Book is generated in HTML, PDF, EPUB, and MOBI formats using [Honkit](https://github.com/honkit/honkit), a framework for writing documentation in Markdown. +The documentation is regularly published on [misp-project.org](https://www.misp-project.org/) and the [CIRCL website](https://www.circl.lu/doc/misp/). ## Documentation guidelines -The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive. -If you notice a problem or some way it can be improved, please edit the documentation. +The documentation is a community effort. +Volunteers work hard to keep it accurate and comprehensive. +If you notice a problem or see a way to improve it, please edit the documentation. All pull requests against MISP must pass review before being merged. -This process is designed to ensure that contributed text is accurate and non-malicious. -Once a pull request passes review, the documentation maintainer then verifies that the pull request is mechanically sound (no merge conflicts or broken links). -If so, the documentation maintainer then merges the pull request. +This process helps ensure that contributed text is accurate and non-malicious. +Once a pull request passes review, the documentation maintainer verifies that it is mechanically sound, such as having no merge conflicts or broken links. +If everything looks good, the maintainer merges the pull request. -If you have a question about something you read in the documentation, you may ask into the [Gitter Support channel](https://gitter.im/MISP/Support) or open an issue for it. -If you see that something in the documentation should be fixed or improved, please [contribute the change](#how-to-make-a-contributution) yourself. +If you have a question about something you read in the documentation, you can ask in the [Gitter Support channel](https://gitter.im/MISP/Support) or open an issue. +If you see documentation that should be fixed or improved, please [contribute the change](#how-to-make-a-contribution) yourself. ## How to make a contribution -Editing the documentation is easy, so if you see that a change should be made, please contribute it! +Editing the documentation is easy, so if you see something that should be changed, please contribute it. A few notes before we get started: -- Every documentation change will be reviewed before it’s accepted. This allows us to maintain quality control and protect our users. -- If your contribution would take a lot of time, please [file an issue](https://github.com/MISP/misp-book/issues) for it first so that we can make sure we’re on the same page before significant work begins. This ensures you do not spend time and effort on a contribution that we can’t accept. +- Every documentation change will be reviewed before it is accepted. This helps us maintain quality and protect our users. +- If your contribution would take a lot of time, please [file an issue](https://github.com/MISP/misp-book/issues) first so we can make sure we are aligned before significant work begins. This helps avoid spending time on a contribution that cannot be accepted. -Thanks to GitHub’s interface, you can edit MISP's documentation even if you don’t know git at all. -All you need to do to contribute is to [fork and clone](https://guides.github.com/activities/forking/) the [misp-book repo](https://github.com/MISP/misp-book/), make your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests/)). -You can also [open issues](https://github.com/MISP/misp-book/issues) if you find any errors or propose changes. +Thanks to GitHub’s interface, you can edit MISP documentation even if you do not know Git. +All you need to do is [fork and clone](https://guides.github.com/activities/forking/) the [misp-book repository](https://github.com/MISP/misp-book/), make your changes, and then [submit a pull request](https://help.github.com/articles/using-pull-requests/). +You can also [open issues](https://github.com/MISP/misp-book/issues) if you find errors or want to propose improvements. -[GitHub workflows](https://docs.github.com/en/actions/using-workflows) (used for automatic integration) is included in misp-book and the book generation is tested at each commit. -When you make a pull request, verify if your changes affect the result of the tests. -If the checks fail, review the output at Travis and make fixes where possible. +[GitHub workflows](https://docs.github.com/en/actions/using-workflows) are used for continuous integration in misp-book, and book generation is tested on each commit. +When you open a pull request, verify whether your changes affect the test results. +If the checks fail, review the workflow output and fix any issues where possible. ### For native English speakers -Most MISP developers are not native English speakers so you're more than welcome to correct or improve our English. -For this, you can either submit a pull request or use another way that suits you better to share your improvements with us. - +Most MISP developers are not native English speakers, so corrections and improvements to our English are especially welcome. +You can submit a pull request or share your improvements in any other way that suits you. ## Organizational guidelines -- Do not duplicate documentation. Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated at some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn’t realize it’s in more than one place). Such traps are often more harmful than if the documentation never existed in the first place. The solution is to link to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare. -- We maintain only one set of documentation for MISP. We do not maintain a different set of documentation for each version of MISP. Our single set of MISP documentation is updated on a continual, rolling basis. Our first priority is to document all current, stable releases of MISP. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. -- Instructions on how to install MISP are held in [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively. +- Do not duplicate documentation. Duplicating documentation is almost always a bad idea because it is easy for one copy to be updated while another is forgotten. In most cases, it is better to link to existing documentation than to repeat it. There are rare exceptions, such as information that is certain not to change for a very long time. +- We maintain only one set of documentation for MISP. We do not maintain a separate set for each version. Our single documentation set is updated on a continual basis. Our first priority is to document all current stable releases of MISP. Our second priority is to document the next upcoming release, if any, that is currently in beta or release candidate status. +- Instructions on how to install MISP are maintained in the [INSTALL](https://github.com/MISP/MISP/tree/2.4/INSTALL) and [download](https://www.misp-project.org/download/) sections of the core and website repositories respectively. ## Style guidelines - Familiarize yourself with the terms defined in the [glossary](https://www.circl.lu/doc/misp/GLOSSARY.html). Use these terms consistently and accurately throughout your writing. -- The language in this book is American English. All the screenshots and examples are in English. +- The language in this book is American English. All screenshots and examples are in English. ## Markdown conventions -All the documentation is written in Markdown for maximum accessibility. When making contributions, please try to observe the following style conventions: +All documentation is written in Markdown for maximum accessibility. +When making contributions, please try to observe the following style conventions: - Use spaces instead of tabs. -- To enable offline browsing, always use relative (rather than absolute) links, e.g., misp/automation/ instead of https://www.circl.lu/doc/misp/automation/. Examples of exceptions: - - URLs that appear inside code blocks (e.g., in comments and code snippets) - - Files like README.md and CONTRIBUTING.md -- Insert a newline at, and only at, the end of each sentence. This practice results in one sentence per line, which is most appropriate for sources that consist primarily of natural language text. It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability. -- If appropriate, make numerals in numbered lists match between Markdown source and HTML output. If a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. -- Use Atx-style headings: `# h1`, `## h2`, `### h3`, etc. -- When writing code blocks, use syntax highlighting where possible and use [...] for anything omitted. -([This](https://daringfireball.net/projects/markdown/) is a great source for learning about Markdown.) +- To enable offline browsing, always use relative links rather than absolute links, such as misp/automation/ instead of https://www.circl.lu/doc/misp/automation/. Exceptions include URLs inside code blocks and files such as README.md and CONTRIBUTING.md. +- Insert a newline at, and only at, the end of each sentence. This results in one sentence per line, which produces more useful diffs and facilitates translation while preserving readability. +- If appropriate, make numerals in numbered lists match between Markdown source and HTML output. If a user needs to read the Markdown source directly, this makes the steps easier to follow. +- Use Atx-style headings: `# h1`, `## h2`, `### h3`, and so on. +- When writing code blocks, use syntax highlighting where possible and use [...] for omitted content. + +([This](https://daringfireball.net/projects/markdown/) is a great resource for learning Markdown.) ## Git conventions @@ -75,4 +75,5 @@ Please try to write good commit messages, according to the [instructions in our ## Translate MISP Book -You can help us make MISP Book available in your language. See [MISP and Internationalization (i18n)](https://www.circl.lu/doc/misp/translation/). +You can help make MISP Book available in your language. +See [MISP and Internationalization (i18n)](https://www.circl.lu/doc/misp/translation/). diff --git a/GLOSSARY.md b/GLOSSARY.md index 9f41cfa..87ad59a 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -1,7 +1,7 @@ ## MISP Glossary -This glossary is meant as a quick lookup document in case of any need of clarification of any threat sharing, threat-intel lingo. -Be careful when adding terms to the glossary. Adding a generic term like: *MISP* will prevent terms like *MISP noticelist* to be addded. As a matter of definition please use the singular for any terms. -In case you use any CCBYSA licensed content, or other pieces that are subject to licensing, make sure to add it as a by-line at the end of the mention. +This glossary is intended as a quick reference for clarifying threat-sharing and threat-intelligence terminology. +Be careful when adding terms to the glossary. Adding a generic term such as *MISP* will prevent more specific terms such as *MISP noticelist* from being added. As a general rule, please use the singular form for each term. +If you use any CC BY-SA licensed content, or any other material that is subject to licensing, make sure to add the appropriate attribution at the end of the entry. ## API MISP makes extensive use of its RESTful API (Application programming interface) both internally and provides an external API for automation, synchronisation or any other tasks requiring a machine to machine interface. @@ -17,7 +17,7 @@ Sharing groups in MISP are a more granular way to create re-usable distribution ## Site admin As an admin (not to be confused with Org Admin), you can set up new accounts for users, edit user profiles, delete them, or just have a look at all the viewers' profiles. -Site admins have access to every administrator feature for all the data located on the system including global features such as the creation and modification of user roles and instance links. You will also see all other organisations connected or setup in the instance. The site admin can be considered as a super-user of a MISP instance. +Site admins have access to every administrator feature for all the data located on the system including global features such as the creation and modification of user roles and instance links. You will also see all other organizations connected to or set up in the instance. The site admin can be considered as a super-user of a MISP instance. ## Indicators Indicators contain a pattern that can be used to detect suspicious or malicious cyber activity. diff --git a/README.md b/README.md index 4f23b90..e322916 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,13 @@ description: Introduction to MISP - Open Source Threat Intelligence Sharing Plat ![MISP logo](https://raw.githubusercontent.com/MISP/MISP/2.4/INSTALL/logos/misp-logo.png) -User guide for MISP - The Open Source Threat Intelligence Sharing Platform. This user guide is intended for ICT professionals such as security analysts, security incident handlers, or malware reverse engineers who share threat intelligence using MISP or integrate MISP into other security monitoring tools. The user guide includes day-to-day usage of the MISP's graphical user interface along with its automated interfaces \(API\), in order to integrate MISP within a security environment and operate one or more MISP instances. +This guide introduces MISP, the open source threat intelligence sharing platform. +It is intended for ICT professionals such as security analysts, incident responders, and malware reverse engineers who share threat intelligence with MISP or integrate MISP into other security monitoring tools. +The guide covers day-to-day use of the MISP graphical user interface together with its automated interfaces (API) so that teams can integrate MISP into their security environment and operate one or more MISP instances. ## Acknowledgement -The MISP user guide is a collaborative effort between all the contributors to [MISP](https://www.github.com/MISP) including: +The MISP user guide is a collaborative effort involving contributors to [MISP](https://www.github.com/MISP), including: * Belgian Ministry of Defence \(CERT\) * [CIRCL Computer Incident Response Center Luxembourg](https://www.circl.lu/) @@ -21,17 +23,18 @@ The MISP user guide is a collaborative effort between all the contributors to [M * Cthulhu Solutions * [CERT-EU](https://cert.europa.eu) -and many other contributors especially the ones during the [MISP hackathons](https://github.com/MISP/MISP/wiki/Hackathon "MISP Hackathon Wiki"). +and many other contributors, especially those who participated in the [MISP hackathons](https://github.com/MISP/MISP/wiki/Hackathon "MISP Hackathon Wiki"). ## Contributing -We welcome contributions to the MISP book. If you want to contribute, see our [contributing guide](/CONTRIBUTING.md) +We welcome contributions to the MISP book. +If you want to contribute, see our [contributing guide](/CONTRIBUTING.md).
## Format -MISP book is available in [HTML](https://www.circl.lu/doc/misp/), [PDF](https://www.circl.lu/doc/misp/book.pdf), [ePub](https://www.circl.lu/doc/misp/book.epub) and [Kindle mobi format](https://www.circl.lu/doc/misp/book.mobi). +The MISP book is available in [HTML](https://www.circl.lu/doc/misp/), [PDF](https://www.circl.lu/doc/misp/book.pdf), [ePub](https://www.circl.lu/doc/misp/book.epub), and [Kindle mobi format](https://www.circl.lu/doc/misp/book.mobi). ## License diff --git a/SUMMARY.md b/SUMMARY.md index 56d5fec..f324529 100755 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -4,16 +4,16 @@ * [Book Convention](book-convention/README.md) * [Quick Start](quick-start/README.md) * [Requirements](requirements/README.md) -* [Get Your Instance](get-your-instance/README.md) +* [Get Your Own MISP Instance](get-your-instance/README.md) * [General Layout](general-layout/README.md) * [General Concepts](general-concepts/README.md) * [User Management and Global Actions](user-management/README.md) * [Using the System](using-the-system/README.md) -* [Delegation of Event](delegation/README.md) -* [Extending Events](extended-events/README.md) +* [Delegation](delegation/README.md) +* [MISP Extended Events](extended-events/README.md) * [Administration](administration/README.md) * [Managing Feeds](managing-feeds/README.md) -* [Updating Python dependencies](updating-python/README.md) +* [Updating Python Dependencies](updating-python/README.md) * [Automation and MISP API](automation/README.md) * [PyMISP - Python Library to Access MISP](pymisp/README.md) * [Create an Event Based on a Report](create-event-report/README.md) @@ -21,19 +21,18 @@ * [Galaxies](galaxy/README.md) * [MISP Objects](misp-objects/README.md) * [Sightings](sightings/README.md) -* [Warning lists](warninglists/README.md) -* [Notice lists](noticelists/README.md) +* [Warning Lists](warninglists/README.md) +* [Notice Lists](noticelists/README.md) * [Categories and Types](categories-and-types/README.md) -* [Synchronisation/Sharing](sharing/README.md) +* [Synchronization and Sharing](sharing/README.md) * [External Connectors](connectors/README.md) * [Modules](modules/README.md) -* [ZeroMQ - MISP publish-subscribe](misp-zmq/README.md) -* [Keyboard shortcuts](keyboard-shortcuts/README.md) +* [ZeroMQ - MISP Publish/Subscribe](misp-zmq/README.md) +* [Keyboard Shortcuts](keyboard-shortcuts/README.md) * [Translations - i18n & l10n](translation/README.md) * [FAQ](faq/README.md) -* [Dev FAQ](dev-faq/README.md) +* [Developer FAQ](dev-faq/README.md) * [Best Practices](best-practices/README.md) -* [User stories](user-stories/README.md) -* [User personas](user-personas/README.md) +* [User Stories](user-stories/README.md) +* [User Personas](user-personas/README.md) * [Appendices](appendices/README.md) - diff --git a/USAGE.md b/USAGE.md index 8af7803..4cd5625 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,9 +1,9 @@ -Install notes -============= +# Install Notes -:warning: Make sure to be in the *misp-book* repository directory for the *npm magic*.
-Reason for concern: +:warning: Make sure you are in the *misp-book* repository directory before running the *npm magic*.
+ +Example output: ``` npm WARN deprecated gulp-header@1.8.12: Removed event-stream from gulp-header npm WARN deprecated har-validator@5.1.5: this library is no longer supported @@ -11,7 +11,7 @@ npm WARN deprecated har-validator@2.0.6: this library is no longer supported npm WARN deprecated cryptiles@2.0.5: This version has been deprecated in accordance with the hapi support policy (hapi.im/support). Please upgrade to the latest version to get the best features, bug fixes, and security patches. If you are unable to upgrade at this time, paid support is available for older versions (hapi.im/commercial). npm WARN deprecated boom@2.10.1: This version has been deprecated in accordance with the hapi support policy (hapi.im/support). Please upgrade to the latest version to get the best features, bug fixes, and security patches. If you are unable to upgrade at this time, paid support is available for older versions (hapi.im/commercial). npm WARN deprecated sntp@1.0.9: This module moved to @hapi/sntp. Please make sure to switch over as this distribution is no longer supported and may contain bugs and critical security issues. -npm WARN deprecated uuid@3.4.0: Please upgrade to version 7 or higher. Older versions may use Math.random() in certain circumstances, which is known to be problematic. See https://v8.dev/blog/math-random for details. +npm WARN deprecated uuid@3.4.0: Please upgrade to version 7 or higher. Older versions may use Math.random() in certain circumstances, which is known to be problematic. See https://v8.dev/blog/math-random for details. npm WARN deprecated tough-cookie@2.2.2: ReDoS vulnerability parsing Set-Cookie https://nodesecurity.io/advisories/130 npm WARN deprecated node-uuid@1.4.8: Use uuid module instead npm WARN deprecated hoek@2.16.3: This version has been deprecated in accordance with the hapi support policy (hapi.im/support). Please upgrade to the latest version to get the best features, bug fixes, and security patches. If you are unable to upgrade at this time, paid support is available for older versions (hapi.im/commercial). @@ -95,11 +95,11 @@ The following plugins are installed and this is how they impact the build. With this plugin you can include GitHub Gists](https://gist.github.com) ``` {% gist id="https://gist.github.com/SteveClement/1ba901612a97d63938ed5cf32c2100ee" %}{% endgist %} - + {% gist id="SteveClement/1ba901612a97d63938ed" %}{% endgist %} - + {% gist id="SteveClement/1ba901612a97d63938ed",file="README.md" %}{% endgist %} - + {% gist id="SteveClement/1ba901612a97d63938ed",hideFooter=true %}{% endgist %} ``` @@ -126,8 +126,8 @@ If you want to generate the PDF output (you need to have Calibre installed): ```bash $ time honkit pdf -info: 13 plugins are installed -info: 13 explicitly listed +info: 13 plugins are installed +info: 13 explicitly listed info: plugin "atoc" is loaded info: plugin "github" is loaded info: plugin "codesnippet" is loaded @@ -141,14 +141,14 @@ info: plugin "search" is loaded info: plugin "lunr" is loaded info: plugin "fontsettings" is loaded info: plugin "theme-default" is loaded -info: found 37 pages -info: found 278 asset files -warn: "options" property is deprecated, use config.get(key) instead -warn: "this.generator" property is deprecated, use "this.output.name" instead -warn: "navigation" property is deprecated -warn: "book" property is deprecated, use "this" directly instead -info: >> generation finished with success in 156.1s ! -info: >> 1 file(s) generated +info: found 37 pages +info: found 278 asset files +warn: "options" property is deprecated, use config.get(key) instead +warn: "this.generator" property is deprecated, use "this.output.name" instead +warn: "navigation" property is deprecated +warn: "book" property is deprecated, use "this" directly instead +info: >> generation finished with success in 156.1s ! +info: >> 1 file(s) generated npx honkit pdf 115.55s user 2.26s system 74% cpu 2:37.29 total ``` @@ -166,8 +166,8 @@ Live reload server started on port: 35729 Press CTRL+C to quit ... Starting server ... -info: 14 plugins are installed -info: 14 explicitly listed +info: 14 plugins are installed +info: 14 explicitly listed info: plugin "atoc" is loaded info: plugin "github" is loaded info: plugin "codesnippet" is loaded @@ -182,14 +182,14 @@ info: plugin "search" is loaded info: plugin "lunr" is loaded info: plugin "fontsettings" is loaded info: plugin "theme-default" is loaded -info: found 37 pages -info: found 277 asset files -warn: "options" property is deprecated, use config.get(key) instead -warn: "this.generator" property is deprecated, use "this.output.name" instead -warn: "navigation" property is deprecated -warn: "book" property is deprecated, use "this" directly instead - -info: >> generation finished with success in 103.7s ! +info: found 37 pages +info: found 277 asset files +warn: "options" property is deprecated, use config.get(key) instead +warn: "this.generator" property is deprecated, use "this.output.name" instead +warn: "navigation" property is deprecated +warn: "book" property is deprecated, use "this" directly instead + +info: >> generation finished with success in 103.7s ! Serving book on http://localhost:4000 ^C npx honkit serve 118.09s user 1.59s system 109% cpu 1:49.14 total diff --git a/book-convention/README.md b/book-convention/README.md index 5d125a2..c1fdd47 100644 --- a/book-convention/README.md +++ b/book-convention/README.md @@ -19,10 +19,11 @@ description: Convention Used in MISP-Book The language in this book is American English. All the screenshots and examples are in English. -## CoC +## Code of Conduct -The same code of conduct applies to this book as for the main MISP project. -As a book can some times be considered the inadvertent soul of a piece of software, please take good care and consideration of our `Code of Conduct`. The CoC [can be read here](https://github.com/MISP/MISP/blob/2.4/code_of_conduct.md). +The same code of conduct applies to this book as to the main MISP project. +Because documentation often reflects the spirit of a software project, please treat the book with the same care and consideration. +You can read the `Code of Conduct` [here](https://github.com/MISP/MISP/blob/2.4/code_of_conduct.md). ## Example install @@ -52,8 +53,8 @@ The following two organisations are regularly used as example: * Setec Astronomy with UUID `58d38339-7b24-4386-b4b4-4c0f950d210f` * Acme Finance with UUID `58d38326-eda8-443a-9fa8-4e12950d210f` -Starting from MISP 2.4.71, the example organisations with the above mentioned UUID are **blocklisted** to avoid -large distribution of sample events while testing a MISP instance. If you want to test your distribution, the +Starting from MISP 2.4.71, the example organisations with the above mentioned UUID are **blocklisted** to avoid +large distribution of sample events while testing a MISP instance. If you want to test your distribution, the sample organisation blocklisting can be removed in `Administration`/`Manage Org blocklists`. ## Example IOCs diff --git a/connectors/README.md b/connectors/README.md index bf87375..ddd36de 100644 --- a/connectors/README.md +++ b/connectors/README.md @@ -1,8 +1,8 @@ # External Connectors -The MISP to Microsoft Graph Security Script enables you to connect your custom threat indicators or Indicators of Comprosmise (IoCs) and make these available in the following Microsoft products. +The **MISP to Microsoft Graph Security Script** lets you export custom threat indicators, or indicators of compromise (IoCs), from MISP to the following Microsoft products. -## Azure Sentinel +## Azure Sentinel [Azure Sentinel](https://azure.microsoft.com/en-us/services/azure-sentinel/) @@ -10,24 +10,25 @@ The MISP to Microsoft Graph Security Script enables you to connect your [Microsoft Defender ATP](https://www.microsoft.com/en-us/microsoft-365/windows/microsoft-defender-atp/) -# MISP to Microsoft Graph Security Script -The script provides clients with MISP instances to migrate threat indicators to the [Microsoft Graph Security API](https://aka.ms/graphsecuritydocs). +## MISP to Microsoft Graph Security Script -For more information on Microsoft Graph Security API visit [Microsoft Graph Security API](https://aka.ms/graphsecuritydocs).
-For more information on Microsoft Graph visit [Microsoft Graph](https://developer.microsoft.com/en-us/graph). +This script enables MISP users to migrate threat indicators to the [Microsoft Graph Security API](https://aka.ms/graphsecuritydocs). +For more information, see the [Microsoft Graph Security API](https://aka.ms/graphsecuritydocs) and [Microsoft Graph](https://developer.microsoft.com/en-us/graph) documentation. ## Prerequisites + Before installing the sample: -* Install Python 3.x version from https://www.python.org/. -* To register your application for access to Microsoft Graph, you'll need either a [Microsoft account](https://www.outlook.com/) or an [Office 365 for business account](https://msdn.microsoft.com/en-us/office/office365/howto/setup-development-environment#bk_Office365Account). If you don't have one of these, you can create a Microsoft account for free at [outlook.com](https://www.outlook.com/). +* Install Python 3.x from https://www.python.org/. +* To register your application for access to Microsoft Graph, you need either a [Microsoft account](https://www.outlook.com/) or an [Office 365 for business account](https://msdn.microsoft.com/en-us/office/office365/howto/setup-development-environment#bk_Office365Account). If you do not already have one, you can create a Microsoft account for free at [outlook.com](https://www.outlook.com/). ## Getting Started -After the prerequisites are installed or met, perform the following steps to use these scripts: + +After you have completed the prerequisites, follow these steps to use the scripts: 1. Download or clone [this repository](https://github.com/microsoftgraph/security-api-solutions/tree/master/Samples/MISP). -1. Go to directory `security-api-solutions/Samples/MISP` -1. Install dependencies. In the command line, run `pip3 install requests requests-futures pymisp` -1. To run script, go to the root directory of misp-graph-script and enter `PYTHONHASHSEED=0 python3 script.py` in the command line. +2. Go to the `security-api-solutions/Samples/MISP` directory. +3. Install the dependencies by running `pip3 install requests requests-futures pymisp`. +4. To run the script, go to the root directory of misp-graph-script and run `PYTHONHASHSEED=0 python3 script.py`. ## App Registration To configure the sample, you'll need to register a new application in the Microsoft [Application Registration Portal](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps). @@ -46,7 +47,7 @@ Follow these steps to register a new application: 1. Under **Application Permissions**, add the permissions/scopes required for the sample. This sample requires **ThreatIndicators.ReadWrite.OwnedBy**. >Note: See the [Microsoft Graph permissions reference](https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference) for more information about Graph's permission model. - + 1. Modify the RequestManager.py file to comment out line 121-124. (This allows the script to run without failing due to line 123 being divided by `avg_speed` incase it starts as `0`. 1. Modify the script.py to add in `config.misp_verifycert` at line 13. Ensure it looks like below. @@ -146,7 +147,7 @@ Possible **action** values are: `alert`, `allow`, `block`. `passiveOnly = False` (This is default). ### Days to Expire -This property is used to specify the amount of days the records will expire in Microsoft Graph Security API. The default value for days to expire is 30. +This property is used to specify the amount of days the records will expire in Microsoft Graph Security API. The default value for days to expire is 30. `days_to_expire = 5` @@ -157,7 +158,7 @@ Configure a sync user. `misp_key = ''` ### Verify Cert -This gives you the option to choose if python should validate the certificate of the misp instance. (This allows ease within testing environments) +This gives you the option to choose if python should validate the certificate of the misp instance. (This allows ease within testing environments) `misp_verifycert = False` IT IS RECOMMENDED TO USE A VALID SSL CERT IN PRODUCTION AND CHANGE THIS TO TRUE diff --git a/create-event-report/README.md b/create-event-report/README.md index 707d5c7..3c96aff 100644 --- a/create-event-report/README.md +++ b/create-event-report/README.md @@ -1,69 +1,69 @@ -## Create an event based on a report +## Create an Event Based on a Report > [warning] A specific permission is required to create an event. -For this example, we will use a report found on [Bleeping Computer](http://www.bleepingcomputer.com/news/security/researcher-finds-the-karma-ransomware-being-distributed-via-pay-per-install-network/), so considered as OSINT. +For this example, we will use a report published on [Bleeping Computer](http://www.bleepingcomputer.com/news/security/researcher-finds-the-karma-ransomware-being-distributed-via-pay-per-install-network/), which we will treat as OSINT. ![Report title](figures/report_title.png) ### Adding an event -First of all, we need to create a new event. To do so, we click the "Add Event" option when on the Events list view. +First, create a new event by clicking **Add Event** in the Events list view. ![Add Event Option](figures/menu_add_event.png) -Then we get the add event form. +This opens the add event form. ![Add Event form](figures/add_event_form.png) -Let's fill it with the data we already have: +Let's populate it with the information we already have: * Date: Here we will put the date of the report, so 2016-11-14 * Distribution: Depending on the event, we might want it to be more or less spread across the MISP instances. For this one, since it is a public report, there is no reason to limit the diffusion so "All communities". -* Threat Level: Self explainatory. Since the ransomware in the report is not using a huge exploit, we can use low, or undefined as we don't really know. we'll go for the latter since it can be edited. +* Threat Level: This is self-explanatory. Since the ransomware described in the report does not appear to use a major exploit, we can choose **Low** or **Undefined**. We will use **Undefined** because it can be refined later. * Analysis: Give the current stage of the analysis. Since the report is published, we can assume that the analysis is completed. -* Event Info: The event's info is in fact the name or title of the event, so it seems legit to put the title of the report here as well. Since it is public information, we also prefix it with "OSINT". +* Event Info: This field is effectively the event title, so it makes sense to use the report title here. Because the source is public, we also prefix it with `OSINT`. * GFI sandbox: Since we don't have any sample or anything here, we leave this alone. ![Add Event form filled](figures/add_event_form_filled.png) -Then just press the blue "Add" button and here we have a brand new event. Empty. +Click the blue **Add** button to create the event. You now have a brand-new, empty event. -![EMPTY EVENT YAY](figures/event_metadata.png) +![EMPTY EVENT YAY](figures/event_metadata.png) (Displayed information can change depending on your role on the MISP instance) ### Adding Attributes -Now it is time to populate this event. But before even adding IoC, we are going to add global information about the report itself: the link of the report and a short explanation or introduction. To do so, we need to click on the "Add Attribute" option in the side menu. This will show us this view: +Now it is time to populate the event. Before adding IoCs, we will add general information about the report itself: the report link and a short introduction. Click **Add Attribute** in the side menu to open the following view: ![add attribute](figures/add_attribute.png) -* First we are going to add the link of the report. Since it has been written by an other researcher, it will be considered as an "External analysis", we choose this category. -* Concerning the type, regarding the kind of data we are adding it is obvious that we will choose the "link" type. +* First, add the link to the report. Because it was written by another researcher, we will treat it as **External analysis** and choose that category. +* For the type, choose **link** because we are adding a URL. * The distribution field can be a little tricky. We can either choose one of the option that was already available at event level or "Inherit event". If we choose the latter, the attribute will be shared the same way as the event it is included in (here to "All communities"). On the other hand, if we choose manually a distribution for the attribute, the most restritive between event distribution and attribute distribution will be applied. That is to say: if both event and attribute distributions are the same, there will be no change (similar to "Inherit event"). However, if for instance the event distribution is "all communities" while the attribute is limited to "This community only", the event will indeed be distributed to all communities but without this particular attribute which will be limited to this community only. The same works the other way around, if the attribute can be distributed to "all communities" while the related event is limited to this community, the attribute being dependant of the event, it will be shared to this community only, basing its distribution on the event (most restrictive) one. -* The value is simply the data we want to add, here it is the link of the report. -* The contextual comment is a field that will not be used for correlation and is mainly there to add some complementary information on the attribute. Can be a port for an IP, or an indication of any type. Here there is no perticular information to add, except maybe tell that it is the source of the report, so let us put this information. +* The value is the data we want to add, which in this case is the report URL. +* The contextual comment is not used for correlation. It is mainly there to provide supporting information about the attribute, such as a port number for an IP address or some other qualifier. Here we can note that the link is the source report. * "for Intrusion Detection System" is used to set the IDS flag or not. If set, the attribute will be used as an IDS signature when exporting the NIDS data. In this case, we have no reason to check it. -* The Batch Import is a useful option when we need to add several IoC of the same category/type which allow you to add them at once by separated by a line break between each line in the value field. However it is of no use here. +* Batch Import is useful when you need to add several IoCs of the same category and type by separating each value with a line break. We do not need it here. ![add attribute filled](figures/add_attribute_filled.png) -All fields are properly filled ? Then let's press the "submit" button, and Ta-dah ! +Once all fields are filled in, click **Submit**. ![attribute added YAY](figures/added_attribute.png) -Now we can do a similar procedure to add an introduction to the report (that is to say the first paragraph of the report). We will simply change the type for text. But this time, we will access the add attribute form by clicking on the small + symbol next to the attribute table. +We can now follow a similar process to add an introduction to the report, meaning the first paragraph of the article. This time, change the type to **text** and open the add attribute form by clicking the small **+** icon next to the attribute table. ![Noooo you found meeeeee](figures/hidden_add_attr.png) -The same form as before will appear in a popup. +The same form appears in a pop-up. ![add attribute popup](figures/add_attr_popup.png) -Again, we fill it with the required data. +Fill it in with the required data. ![add attribute popup](figures/filled_popup.png) -Then we submit it by clicking on the blue button +Then submit it by clicking the blue button. _Et voilà!_ ![MAGIC](figures/popadded.png) @@ -90,7 +90,7 @@ So we begin with the filename. No real change from before for this one, except t Then we can add the hashes in a similar way. We will had them both alone and combined with the filename. In order to do it quickly, we are going to use the freetext import tool, hidden there -![freetext import step 1](figures/freeeeeimport.png) +![freetext import step 1](figures/freeeeeimport.png) It will open a popup with a text area field where we will paste our IoC, one per line. As said previously, we add both the hashes alone and with the filename. @@ -100,11 +100,11 @@ Then when we press the submit button, we are redirected on this page to control ![freetext import step 3](figures/freeresults.png) -Here, MISP detected by itself what should be the category and type associated to our IoC and surprise! It matches our suppositions. Plus, it also put the IDS flag, so it is perfect. But before submitting, please double check to be sure all the values are correct and no information was lost (That can happen when the data are not formatted as expected by MISP). +Here, MISP detected by itself what should be the category and type associated to our IoC and surprise! It matches our suppositions. Plus, it also put the IDS flag, so it is perfect. But before submitting, please double check to be sure all the values are correct and no information was lost (That can happen when the data are not formatted as expected by MISP). If the results of MISP were not what we expected, we can still modify it, however MISP will only suggest suitable category/type regarding the format of your data. We can change for each attribute individually or all at the same time using the option on the bottom right of the form. The same principle also applies for the comments, individually or for all. -![freetext import suggestions](figures/freesuggest.png) +![freetext import suggestions](figures/freesuggest.png) (Yes I have two cursors, MISP is magic!) We only have the network indicators left, and as said before, we will let MISP determined for us which type is the best for the data we have. @@ -113,21 +113,21 @@ We only have the network indicators left, and as said before, we will let MISP d ![type recognition fail](figures/surprise.png) -Oh well, that was unexpected. In fact, it is not that surprising regarding the format of the tor address that look more like a filename than like a url but it is still a problem, since we can't change the type nor the category to a more consistent one. This is indeed one of the limitation of freetext import. To solve this issue, we will use a simple trick: we will add a slash at the end of the tor address so it won't be confused for a filename. +Oh well, that was unexpected. In fact, it is not that surprising regarding the format of the tor address that look more like a filename than like a url but it is still a problem, since we can't change the type nor the category to a more consistent one. This is indeed one of the limitation of freetext import. To solve this issue, we will use a simple trick: we will add a slash at the end of the tor address so it won't be confused for a filename. ![freetext import network](figures/free_network2.png) ![type recognition fail](figures/nomoresurprise.png) -Thanks to the added character, the first string is recognised as an url which is more consistent with the reality. The second also seems okay, so we can now submit both. +Thanks to the added character, the first string is recognised as an url which is more consistent with the reality. The second also seems okay, so we can now submit both. ### Batch Import -The Freetext Import works properly only with a string of data without any spaces in one line. But if you have lines of text with spaces between values, like e.g. +The Freetext Import works properly only with a string of data without any spaces in one line. But if you have lines of text with spaces between values, like e.g. ![freetext_with_spaces1](figures/freetext_with_spaces1.png) -you can still import them at once using the "Add Attribute" option. Click on _Add Attribute_, copy the data and paste it into the _Value_ box. Choose the right category and type. Now check both checkboxes _for Intrusion Detection System_ and _Batch Import_. The option _Batch Import_ will import your data line for line just like the _Freetext Import_ option without losing any information. Like this: +you can still import them at once using the "Add Attribute" option. Click on _Add Attribute_, copy the data and paste it into the _Value_ box. Choose the right category and type. Now check both checkboxes _for Intrusion Detection System_ and _Batch Import_. The option _Batch Import_ will import your data line for line just like the _Freetext Import_ option without losing any information. Like this: ![addattribute_freetext](figures/addattribute_freetext.png) @@ -135,4 +135,4 @@ And that is all we can get for the main informations and IoC in this report. If ### Modify the event -If you want to modify your event from the home page, you can either double click on the event or click the edit symbol located in the column __Actions__ on the right side. You will be redirected to the editing mode of the selected event. +If you want to modify your event from the home page, you can either double click on the event or click the edit symbol located in the column __Actions__ on the right side. You will be redirected to the editing mode of the selected event. diff --git a/delegation/README.md b/delegation/README.md index 711c60b..0a57b79 100644 --- a/delegation/README.md +++ b/delegation/README.md @@ -1,53 +1,62 @@ # Delegation -In information sharing, privacy of the reporting organisation can be important in such case as: +In information sharing, the privacy of the reporting organization can be important in cases such as: -- an incident doesn't want to be linked to a potential victim. -- to avoid the relation of an organisation with the information shared. +- when an incident should not be linked to a potential victim. +- when you want to avoid linking a specific organization to the shared information. -MISP has a functionality to delegate the publication and completely remove the binding between the information shared and its organisation. If you want to publish an event without you or your organisation being tied to it, you can delegate the publication to an other organisation. That also means they will take the ownership of the event. You can only delegate to local target organisations, not any remote organisations. +MISP includes a delegation feature that lets another organization publish an event on your behalf and removes the direct link between the shared information and your organization. +If you want to publish an event without your organization being tied to it, you can delegate publication to another organization. +That organization becomes the owner of the event. +You can delegate only to local target organizations, not to remote ones. -> [warning] You need to have a role with "Delegation access" to delegate an event. -> -> [warning] Also activate MISP.delegation parameter in your instance. +> [warning] You need a role with `Delegation access` to delegate an event. +> +> [warning] You must also enable the `MISP.delegation` parameter on your instance. ### Send a delegation request -To do so, you first need to put the distribution of the event as "your organisation only". -![Delegation possible](./figures/delegationpossible.png) -Otherwise the delegation option will not be available. -![Delegation impossible](./figures/delegationimpossible.png) - -When the "Delegate Publishing" option is clicked, a pop-up will show up: -![Delegation Popup](./figures/delagationpopup.png) -Here you can choose -- to which organisation you wish to delegate the event among all those registered on the server. For this example we are going to ask Setec Astronomy to publish the event for us. -- The distribution option you would like to put on the event. You can let the other organisation (called "recipient") choose if you don't mind it. For this example, we will request the recipient to share it to all communities, but it is only a suggestion, and the recipient will be able to modify the diffusion setting if wanted. -![Desired Distribution](./figures/desireddistribution.png) -- Finally you can leave a free message to the recipient organisation. -![Distribution ready](./figures/delegationpopup2.png) - -Once the request is sent, a message will appear on the event to remind you of your request. -![Reminder](./figures/delegationrequested.png) -You can also see more details by clicking on "View request details" -![Request Details](./figures/requestdetails.png) -And you can also discard the request your self, by using this pop-up or the link in the left menu. +To do this, you first need to set the event distribution to **Your organization only**. +![Delegation possible](./figures/delegationpossible.png) +Otherwise, the delegation option will not be available. +![Delegation impossible](./figures/delegationimpossible.png) + +When you click **Delegate Publishing**, a pop-up appears. +![Delegation Popup](./figures/delagationpopup.png) +Here you can choose the following options: +- The organization to which you want to delegate the event. + In this example, we ask Setec Astronomy to publish the event for us. +- The distribution option you would like to request for the event. + You can let the recipient organization choose if you do not mind. + In this example, we request **All communities**, but this is only a suggestion and the recipient can still change the distribution later. +![Desired Distribution](./figures/desireddistribution.png) +- An optional free-form message to the recipient organization. +![Distribution ready](./figures/delegationpopup2.png) + +Once the request is sent, a message appears on the event to remind you that the request is pending. +![Reminder](./figures/delegationrequested.png) +You can also view more details by clicking **View request details**. +![Request Details](./figures/requestdetails.png) +You can discard the request yourself by using either this pop-up or the link in the left-side menu. ### Answer a delegation request -As the recipient organisation, you will then receive the request of delegation. You will be notified by a red circle around the envelope on the top right of the screen. -![Notification](./figures/delegationwaiting.png) -When you click it, you will be redirected as usual on the dashboard, where we can see one delegation request on the left frame. -![Dashboard](./figures/dashboard.png) -Clicking on the "view" link then redirect to an event list view showing all the events other organisations wish to delegate to your organisation. Here we only see one event, from Acme Factory. -![Delegated list](./figures/delagated.png) -And here are the metadata of the so called event. -![Delegated event](./figures/delegatedevent.png) -You will be able to view the details by clicking the so called link. -![Delegated event](./figures/recipientdetails.png) -If your role have publishing rights, you will be able to manage the delegation request by using one of the two links in the left menu. -You can either discard it: -![Discard request](./figures/discarddelegation.png) -Or accept the delegation: -![Accept request](./figures/acceptdelegation.png) -Please notice that the distribution desired by the requester will not automatically be set on the event, which will stay as distributed to your own organisation only if the parameter is not modified. +As the recipient organization, you receive the delegation request. +You are notified by a red circle around the envelope in the upper-right corner of the screen. +![Notification](./figures/delegationwaiting.png) +When you click it, you are redirected to the dashboard, where the delegation request appears in the left pane. +![Dashboard](./figures/dashboard.png) +Click **View** to open an event list showing all events that other organizations want to delegate to your organization. +In this example, we see a single event from Acme Factory. +![Delegated list](./figures/delagated.png) +Here are the metadata for that event. +![Delegated event](./figures/delegatedevent.png) +You can view the full details by clicking the corresponding link. +![Delegated event](./figures/recipientdetails.png) +If your role includes publishing rights, you can manage the delegation request by using one of the two links in the left-side menu. +You can either discard it: +![Discard request](./figures/discarddelegation.png) +Or accept it: +![Accept request](./figures/acceptdelegation.png) +Note that the distribution requested by the original sender is not applied automatically. +If the setting is not changed, the event remains distributed only to your own organization. diff --git a/extended-events/README.md b/extended-events/README.md index df94b77..6b3db65 100644 --- a/extended-events/README.md +++ b/extended-events/README.md @@ -1,4 +1,6 @@ # MISP Extended Events -MISP can now extend an event (starting from version 2.4.90). This allows users to build full blown events that extend an existing event, giving way to a combined event view that includes a sum total of the event along with all extending events. +Starting with version 2.4.90, MISP can extend an event. +This allows users to build full events that extend an existing one, creating a combined event view that includes the original event together with all extending events. + [More](http://www.misp-project.org/2018/04/19/Extended-Events-Feature.html) diff --git a/get-your-instance/README.md b/get-your-instance/README.md index 3d6140d..1ed9beb 100644 --- a/get-your-instance/README.md +++ b/get-your-instance/README.md @@ -1,20 +1,20 @@ -## Get your own MISP instance +## Get Your Own MISP Instance -The intention of this chapter is to support you in getting your own MISP instance up and running. +The goal of this chapter is to help you get your own MISP instance up and running. ### MISP Virtual Machine -CIRCL maintains the image of a recent MISP virtual machine online. This VM is generated after every commit to the main MISP repository on Github. +CIRCL maintains an up-to-date MISP virtual machine image online. This VM is generated after every commit to the main MISP repository on GitHub. -This is a very easy out of the box solution, optimized for product evaluation and to support trainings held by CIRCL staff. +It is an easy out-of-the-box option that is well suited to product evaluation and to training sessions run by CIRCL staff. #### MISP VM Download -The best place to get the latest version of the MISP virtual machine, as well as all the available training materials is the [MISP training materials page] [1] on the CIRCL website. +The best place to get the latest MISP virtual machine image, along with the available training materials, is the [MISP training materials page] [1] on the CIRCL website. -If you do not remember the direct link to the MISP training materials here are the very easy to remember steps you have to follow to reach the right place: +If you do not remember the direct link, follow these steps to find it: 1. Access the [CIRCL homepage] [2] 2. Navigate to the [Training area] [3] @@ -30,9 +30,9 @@ In VirtualBox use the "Import Appliance..." functionality to import the virtual ![Import Appliance...](figures/importApp.png) -The instructions in this manual covers VirtualBox only. If you prefer another virtualization solution like VMWare you can find some quick instruction on the [MISP training materials page] [1]. +The instructions in this manual cover VirtualBox only. If you prefer another virtualization solution, such as VMware, you can find brief instructions on the [MISP training materials page] [1]. -ESXi Servers have been tested too. Should work without problem but some manual changing of the ATA-Bus is needed. +ESXi servers have also been tested. They should work, but you may need to adjust the ATA bus manually. #### MISP VM Credentials @@ -44,7 +44,7 @@ You should have two interfaces on your VirtualBox configuration (NAT and host-on Depending on your setup (for example accessing the VM from another host), you might want to change the base URL in MISP server settings. This can be done from the command line: sudo -u www-data /var/www/MISP/app/Console/cake Baseurl [baseurl] - + You can confirm the baseurl is updated correctly by checking the config.php file: grep baseurl /var/www/MISP/app/Config/config.php @@ -62,7 +62,7 @@ MISP credentials: #### Networking on the VM -Virtualbox has a neat feature to forward ports from your Host machine to the Guest VM. +VirtualBox includes a convenient feature for forwarding ports from your host machine to the guest VM. We forward the following ports: * **ssh** Forward from 2222 on Host -> 22 on guest @@ -72,9 +72,9 @@ We forward the following ports: * **8888** Viper Web UI - 8888 on Host -> 8888 on guest * **1666** misp-modules used to poll the misp-modules API - 1666 on Host -> 6666 on guest -If the port is already used on your host, virtualbox will still boot and all the other ports will work. +If a port is already in use on your host, VirtualBox will still boot and the other forwarded ports will continue to work. -To change the port forwarding select the running VM in the UI and click on `Settings` -> `Network` -> `Advanced` -> `Port forwarding` +To change the port forwarding, select the running VM in the UI and click `Settings` -> `Network` -> `Advanced` -> `Port forwarding`. ![Overview of Network settings](figures/vbox-settings-forwarding.png) @@ -97,4 +97,4 @@ Either configure the port forwards manually or download a new VM. [1]: https://www.circl.lu/services/misp-training-materials/ "MISP training materials page" [2]: https://www.circl.lu/ "CIRCL homepage" [3]: https://www.circl.lu/services/training/ "Training area" -[4]: https://www.circl.lu/services/training/#misp-malware-information-sharing-platform-threat-sharing "Malware Information Sharing Platform" \ No newline at end of file +[4]: https://www.circl.lu/services/training/#misp-malware-information-sharing-platform-threat-sharing "Malware Information Sharing Platform" diff --git a/modules/README.md b/modules/README.md index 4b8ebfa..a773865 100644 --- a/modules/README.md +++ b/modules/README.md @@ -1,16 +1,18 @@ -# MISP modules +# MISP Modules -MISP modules are autonomous modules that can be used for expansion and other services in MISP. -The modules are written in Python 3 following a simple API interface. The objective is to ease the extensions of MISP functionalities without modifying core components. The API is available via a simple REST API which is independent from MISP installation or configuration. +MISP modules are self-contained modules that provide expansion and other services for MISP. +They are written in Python 3 and follow a simple API interface. +The goal is to extend MISP functionality without modifying core components. +The API is exposed through a REST interface that is independent of the main MISP installation and configuration. -MISP modules support is included in MISP starting from version 2.4.28. +Support for MISP modules is included in MISP starting with version 2.4.28. [More](https://www.circl.lu/assets/files/misp-training/switch2016/2-misp-modules.pdf) -[MISP modules GitHub Repo](https://github.com/MISP/misp-modules) +[MISP Modules GitHub Repository](https://github.com/MISP/misp-modules) ## Installation -[Install guide on Ubuntu](https://github.com/MISP/misp-modules#how-to-install-and-start-misp-modules-in-a-python-virtualenv-recommended) +[Installation guide for Ubuntu](https://github.com/MISP/misp-modules#how-to-install-and-start-misp-modules-in-a-python-virtualenv-recommended) -[Install guide RHEL/CentOS](https://github.com/MISP/misp-modules#how-to-install-and-start-misp-modules-on-rhel-based-distributions-) +[Installation guide for RHEL/CentOS](https://github.com/MISP/misp-modules#how-to-install-and-start-misp-modules-on-rhel-based-distributions-) diff --git a/noticelists/README.md b/noticelists/README.md index 3554b9c..4f8a12c 100644 --- a/noticelists/README.md +++ b/noticelists/README.md @@ -1,7 +1,7 @@ -# MISP noticelist +# MISP Notice Lists -Notice lists to inform MISP users of the legal, privacy, policy or even technical implications of using specific attributes, categories or objects. -[MISP noticelist GitHub Repo](https://github.com/MISP/misp-noticelist) +Notice lists inform MISP users about the legal, privacy, policy, or technical implications of using specific attributes, categories, or objects. +[MISP Notice List GitHub Repository](https://github.com/MISP/misp-noticelist) -MISP Noticelists are a simple JSON description to trigger warning notifications to make the user more aware of eventual implications of her actions. +MISP notice lists use a simple JSON description to trigger informational warnings and make users more aware of the possible implications of their actions. diff --git a/pymisp/README.md b/pymisp/README.md index aad3083..a299945 100644 --- a/pymisp/README.md +++ b/pymisp/README.md @@ -1,10 +1,10 @@ -## PyMISP - Python Library to access MISP +## PyMISP - Python Library to Access MISP -PyMISP is a Python library to access MISP platforms via their REST API. +PyMISP is a Python library for accessing MISP platforms through their REST API. -PyMISP allows you to fetch events, add or update events/attributes, add or update samples or search for attributes. +PyMISP lets you fetch events, add or update events and attributes, add or update samples, and search for attributes. -Note that you need to have Auth Key access in your MISP instance to use PyMISP +You need Auth Key access on your MISP instance to use PyMISP. ### Capabilities @@ -19,11 +19,11 @@ Note that you need to have Auth Key access in your MISP instance to use PyMISP * Full text search and search by attributes * Get STIX event * Export statistics -And even more, just look at the api.py file +And more. See `api.py` for the full list. ### Installation -You can install PyMISP by either using pip or by getting the last version from the [GitHub repository](https://github.com/MISP/PyMISP) +You can install PyMISP either with pip or by retrieving the latest version from the [GitHub repository](https://github.com/MISP/PyMISP). #### Install from pip ~~~~ @@ -52,19 +52,19 @@ or on your profile https:///users/view/me ~~~~ -If you did not install using the repository, you can still fetch it to get examples to work on: +If you did not install from the repository, you can still clone it to access the examples: ~~~~ git clone https://github.com/MISP/PyMISP.git ~~~~ -In order to use these, you need to create a file named keys.py in the examples folder and edit it to put the url of your MISP instance and your automation key. +To use these examples, create a file named `keys.py` in the `examples` folder and add the URL of your MISP instance together with your automation key. ~~~~ cd examples cp keys.py.sample keys.py vim keys.py ~~~~ -Once you are done with it, you are ready to start. +Once you have done that, you are ready to start. This is how **keys.py** looks: @@ -72,8 +72,8 @@ This is how **keys.py** looks: ### Using PyMISP -To have a better understanding of how to use PyMISP, we will have a look at one of the existing examples: add\_named\_attribute.py -This script allow us to add an attribute to an existing event while knowing only its type (the category is determined by default). +To better understand how to use PyMISP, let us look at one of the existing examples: `add_named_attribute.py`. +This script allows us to add an attribute to an existing event while knowing only its type, because the category is determined automatically. ~~~~python #!/usr/bin/env python # -*- coding: utf-8 -*- @@ -121,7 +121,7 @@ Thanks to the previously created function, we create a PyMISP object. ~~~~ In order to add the new argument, we first need to fetch the event in the MISP database using the [get\_event](https://github.com/CIRCL/PyMISP/blob/master/pymisp/api.py#L223) function which only need the event\_id. Then only once we have it, we can call the function [add\_named\_attribute](https://github.com/CIRCL/PyMISP/blob/master/pymisp/api.py#L372) that will add the argument. ~~~~python - print(event) + print(event) ~~~~ Finally the new event is printed, so we can check that the attribute was correctly added, and that a category was attached to it automatically. diff --git a/translation/README.md b/translation/README.md index 9f5d3ce..0ac64cb 100644 --- a/translation/README.md +++ b/translation/README.md @@ -6,8 +6,9 @@ Please read the following [CakePHP documentation about i18n & l10n](https://book ## Add one .md per translation effort -Please add a file à la: ja_JP.md (Japanese_Japan) or it_CH.md (Italian_Switzerland), in which you briefly describe what the current status of your translation effort is and what has been translated and which parts might be gotchas. -This would also be a good place to quickly explain what your language is about, like whether most technical terms are a translation from the original, an adaptation from the English word or perhaps you just mostly use English terms. +Please add one Markdown file per translation effort, such as `ja_JP.md` (Japanese_Japan) or `it_CH.md` (Italian_Switzerland). +In that file, briefly describe the current status of the translation, what has already been translated, and any sections that may be tricky. +It is also a good place to explain how technical terms are handled in your language, for example whether they are translated directly, adapted from English, or usually kept in English. ## Style @@ -27,7 +28,9 @@ You want to have ultimate flexibility and that line should look more like this:

``` -In the above example we use an alternative notation of the format string in PHP. Using the above, the generated po-template file ([default.pot](https://github.com/MISP/MISP/blob/2.4/app/Locale/default.pot)) will have the name of the to-be-translated variable in the "msgid" part of the file. Which is easier to read then a non descriptive %s and allows the translator to have context on how the phrase is used in MISP. +In the above example, we use an alternative notation for the PHP format string. +With this approach, the generated po-template file ([default.pot](https://github.com/MISP/MISP/blob/2.4/app/Locale/default.pot)) includes the name of the variable to be translated in the `msgid` entry. +That is easier to read than a non-descriptive `%s` and gives the translator more context about how the phrase is used in MISP. In case you have HTML-Tags, move them out of the sentence, out of the php code if possible: ``` @@ -42,9 +45,9 @@ In case you have HTML-Tags, move them out of the sentence, out of the php code i ## Issues -Some times it might be impossible to translate some phrases. -Or you notice a certain bad formatting, or segmentation of sentences. -In that case, please either open an [Issue on Github](https://github.com/MISP/MISP/issues) +Sometimes it may be impossible to translate certain phrases. +You might also notice bad formatting or awkward sentence segmentation. +In that case, please open an [issue on GitHub](https://github.com/MISP/MISP/issues). ## Quirks diff --git a/updating-python/README.md b/updating-python/README.md index 5bf376b..ea97b38 100644 --- a/updating-python/README.md +++ b/updating-python/README.md @@ -1,19 +1,19 @@ # Updating Python Dependencies -MISP requires a couple of python libraries to be installed for the entire set of functionalities to work properly. +MISP requires several Python libraries for its full feature set to work correctly. -These functionalities include for instance the different import and export tools, the binaries extraction from attachments or PyMISP. +These features include the import and export tools, binary extraction from attachments, and PyMISP. ------ ## Installation -We started using virtual environments in MISP to make the installation and maintenance of the python versions easier. +MISP uses virtual environments to make Python installation and maintenance easier. -Either using the [installation script](https://github.com/MISP/MISP/blob/2.4/INSTALL/INSTALL.sh) to setup a running MISP on your machine, or starting using the automatically generated [virtual machine](https://www.circl.lu/misp-images/latest/) will give you access to the latest version of the required python libraries installed within a virtual environment called `virtualenv`. +If you use the [installation script](https://github.com/MISP/MISP/blob/2.4/INSTALL/INSTALL.sh) to set up MISP on your machine, or start from the automatically generated [virtual machine](https://www.circl.lu/misp-images/latest/), you already have the latest required Python libraries installed in a virtual environment. -But if you are using an older MISP version, you may want to install the virtual environment +If you are using an older MISP version, you may want to create the virtual environment manually. -#### Set the virtual environment up +#### Set Up the Virtual Environment ~~~~bash # Create a python3 virtualenv sudo -H -u www-data virtualenv -p python3 /var/www/MISP/venv @@ -22,18 +22,18 @@ sudo -H -u www-data virtualenv -p python3 /var/www/MISP/venv sudo mkdir /var/www/.cache sudo chown www-data:www-data /var/www/.cache ~~~~ -If you already have a `venv` directory, you can skip this step +If you already have a `venv` directory, you can skip this step. ------ ## Updating MISP and its dependencies -Keeping MISP up-to-date as much as possible is the safest way to avoid most of the potential issues. +Keeping MISP as up to date as possible is the safest way to avoid most potential issues. -It can be done either by using the Update button in the diagnostic tool available with the MISP UI, or by using the command line. +You can do this either from the Update button in the diagnostic tool in the MISP UI or from the command line. ### Updating MISP core -In order to update MISP dependencies, we first want to pull the latest MISP version, so we have the latest submodule references as well. +To update MISP dependencies, first pull the latest MISP version so you also get the latest submodule references. ![Update MISP from the diagnostic tool in the UI](figures/update_diagnostic.png) @@ -42,22 +42,22 @@ OR sudo -H -u www-data git pull origin 2.4 ~~~~ -Once we have the latest MISP update, we can start updating the python libraries. +Once you have the latest MISP update, you can start updating the Python libraries. ### Updating the python dependencies -MISP is provided with a lot of submodules used to ensure all the additional functionalities work as expected. Thus it is important to keep those dependencies up-to-date. +MISP includes several submodules that support additional functionality, so it is important to keep those dependencies up to date. ~~~~bash sudo -H -u www-data git submodule update --init --recursive ~~~~ #### Updating python dependencies -It is possible to check the status of all the python libraries required by MISP, using again the diagnostic tool. +You can check the status of all Python libraries required by MISP by using the diagnostic tool again. ![Python libraries status](figures/python_diagnostic.png) -If something is going wrong, updating the corresponding library will make the diagnostic happy. +If something is wrong, updating the corresponding library should resolve the diagnostic warning. ~~~~bash # Update PyMISP cd /var/www/MISP/PyMISP @@ -68,7 +68,7 @@ sudo -H -u www-data /var/www/MISP/venv/bin/pip install -U . sudo -H -u www-data /var/www/MISP/venv/bin/pip install -U lief # python-magic sudo -H -u www-data /var/www/MISP/venv/bin/pip install -U python-magic -# pydeep - WARNING: It requires libfuzzy-dev +# pydeep - WARNING: It requires libfuzzy-dev sudo -H -u www-data /var/www/MISP/venv/bin/pip install -U pydeep # Update the STIX dependencies (PICK THE ONE.S YOU NEED TO UPDATE) diff --git a/user-personas/README.md b/user-personas/README.md index 75c3966..ced2342 100644 --- a/user-personas/README.md +++ b/user-personas/README.md @@ -1,8 +1,8 @@ -# MISP user personas +# MISP User Personas -These personas are fictitious but are concrete representations of the people using MISP. -We can use these personas to keep in mind who we are working for, what are their needs, and what MISP should do for them. -These personas come from OSINT on current MISP users (Gitter chats, GitHub issues, LinkedIn) and other sources of information about cybersecurity. +These personas are fictional, but they are based on concrete representations of the people who use MISP. +They help us keep in mind who we are building for, what their needs are, and what MISP should help them accomplish. +These personas are based on OSINT about current MISP users, including Gitter chats, GitHub issues, LinkedIn, and other cybersecurity sources. ## Primary personas Farrah and Adam represent the users that are the most important to us. @@ -10,18 +10,18 @@ Farrah and Adam represent the users that are the most important to us. ### Farrah _**The Threat Hunter**_ -Farrah works as a threat intelligence for a security service provider in Malaysia that offers a range of cybersecurity solutions. +Farrah works in threat intelligence for a security service provider in Malaysia that offers a range of cybersecurity solutions. He leads a threat intelligence team made up of experienced intelligence analysts who are former military/government employees and contractors. -Farrah uses MISP to analyze malware, gather information about specific adversary groups, and discover emerging threats. +Farrah uses MISP to analyze malware, gather information about specific adversary groups, and discover emerging threats. He also uses MISP for data normalization (consolidating data across different source formats), de-duplication (removal of duplicate information), and enrichment (removal of false positives, scoring of indicators, and the addition of context). -_"In order to effectively address threats, you must maintain a team focused on monitoring, generating and triaging alerts"_ +_"To address threats effectively, you must maintain a team focused on monitoring, generating, and triaging alerts."_ #### Role Lead Threat Intelligence Analyst -#### His primary goals are to: +#### His primary goals are to: - Hunt down threats, analyze malware, manage vulnerabilities and prevent attacks against ICT infrastructures, organizations, or people. - Improve security posture through the aggregation, correlation, and analysis of threat data from multiple sources - Investigate and understand adversarial capabilities, infrastructure & TTPs. @@ -39,12 +39,12 @@ Lead Threat Intelligence Analyst - Aggregate, curate, and validate indicators from various feeds, then feed the data into detection and analysis tools like NIDs, IDS, and SIEMs - Query vulnerability scan results in MISP, automatically create/classify events on matching results, then create blocklists by excluding attributes that exist on warning lists. - Collaborate with others in a sharing community using Proposals (send and receive feedback), Extended Events (add additional information to other’s analytics), and Event Reports (supply resolution steps and recommendations). -- Share and receive reports of a specific threat, false positives, or post-mortem analysis of an incident from sharing groups. +- Share and receive reports of a specific threat, false positives, or post-mortem analysis of an incident from sharing groups. #### His objectives are to: - Join relevant sharing communities, produce and publish indicators and share information across sectors to avoid hybrid threats. - Use IoCs from feeds to identify vulnerabilities, compromised assets, data leaks and to verify the results of a malware scan. -- Triage threat intel, prioritize vulnerabilities, and customize risk feeds to ignore or downgrade irrelevant alerts in order to avoid alert fatigue. +- Triage threat intel, prioritize vulnerabilities, and customize risk feeds to ignore or downgrade irrelevant alerts in order to avoid alert fatigue. - Generate and share alerts to provide critical information to internal teams and external peers. - Share information about relevant vulnerabilities, coordinate with security vendors to get notifications, and community sharing of pentest results with other analysts. - Research the evolution of high-risk malware families, validate malware signatures and domain reputations. @@ -56,8 +56,8 @@ Lead Threat Intelligence Analyst ### Adam _**The Remediator**_ -Adam is part of the Computer Security Incident Response Team (CSIRT) at a Belgian cybersecurity consulting firm. -His responsibilities involve incident response, incident coordination, threat intelligence, and vulnerability management. +Adam is part of the Computer Security Incident Response Team (CSIRT) at a Belgian cybersecurity consulting firm. +His responsibilities involve incident response, incident coordination, threat intelligence, and vulnerability management. He monitors potential threats, investigates attacks, and works with other security personnel to reduce the impact and severity of an attack. Adam uses MISP to monitor incidents, provide early warnings/alerts about incidents, respond to incidents and provide incident analysis and situational awareness. @@ -71,20 +71,20 @@ Incident Response - Uncover the effects of attacks, determine how to clean up its impact, and inform a response to an existing incident to mitigate its extent or impacts. - Develop and maintain strong processes for the most common incidents and threats, and create actionable results and remediation plans for internal stakeholders to proactively improve the security posture and maturity. -- Accelerate incident investigations, management, and prioritization by looking for information on the who/what/why/when/how of an incident. +- Accelerate incident investigations, management, and prioritization by looking for information on the who/what/why/when/how of an incident. - Determine the scope of incidents and limit the potential damage. #### He uses MISP to: - Store incidents as a database of events, describe incidents through event classification (using taxonomies and galaxies) and use the API to deduce from all incidents the current operational status, risk posture, and threats to the cyber environment. - Join sharing groups and communities to share incident information with others and discuss information related to risks associated with incidents via Forums, comments to events, and contact a reporter. -- Analyze observables/malware collected during an incident, determining whether they are IoCs or false positives using the correlation graph and expansion modules. -- Alert and send emails when events are created in the system or major changes occur in the events, serving as part of an early warning system. +- Analyze observables/malware collected during an incident, determining whether they are IoCs or false positives using the correlation graph and expansion modules. +- Alert and send emails when events are created in the system or major changes occur in the events, serving as part of an early warning system. - Pull events via the API or export IOCs in formats for easy ingestion into other tools (such as SIEMs and IDS) and carrying out investigations by launching lookups against databases. - Collaborate and get feedback from team members and affected parties during incident response using Proposals. -- Dismiss false positives (using warning lists) and enable alert prioritization. +- Dismiss false positives (using warning lists) and enable alert prioritization. - Aggregate and compare information from internal and external feeds to identify genuine threats. - Perform large-scale data/traffic analysis and correlation through lookups against SightingDB. -- Share, receive, store and forward incidents and information identified during an incident investigation, enabling the MISP system to act as a forensic tool over time. +- Share, receive, store and forward incidents and information identified during an incident investigation, enabling the MISP system to act as a forensic tool over time. - Correlate and reference network forensic flows from different tools or network equipment - Speed up incident response via integration with TheHive. @@ -140,7 +140,7 @@ Fraud analyst ### Henry _**The Enforcer**_ -Henry is a law enforcement officer living in Florida, USA. He works with the Digital Forensics and Incident Response (DFIR) team. +Henry is a law enforcement officer living in Florida, USA. He works with the Digital Forensics and Incident Response (DFIR) team. He is responsible for investigating digital security incidents, identifying digital assets targeted during attacks, and documenting all findings. He uses MISP to support or bootstrap his DFIR cases. @@ -151,15 +151,15 @@ _"I worry about what I don’t know, not what I know"_ Law Enforcement Officer #### His primary goals are to: -- Find, gather and analyze digital evidence for criminal investigations. +- Find, gather and analyze digital evidence for criminal investigations. - Carry out data breach and malware investigations. #### He uses MISP to: - Propose changes to existing analyses or reports. -- Correlate (1-to-1 value matches, fuzzy hashing, CIDR block matching) evidence against external/local attributes. +- Correlate (1-to-1 value matches, fuzzy hashing, CIDR block matching) evidence against external/local attributes. - Correlate and reference network forensic flows from different tools or network equipment using the community-id feature. - Export data in various formats to feed into and lookup in other security tools. -- Join sharing groups and collaborate with other investigators. +- Join sharing groups and collaborate with other investigators. - Receive, gather, analyze and share intelligence on digital crimes. - Report digital evidence (in STIX) in a structured way for forensic use. - Collect evidence for forensic analysis from feeds, using shared indicators to carry out cybercriminal behavior investigations, attribution, and identifying the link to organized crime activities. @@ -175,10 +175,10 @@ Law Enforcement Officer ### Jacob _**The Veteran**_ -Jacob is a cybersecurity consultant for organizations looking to secure their infrastructure. -He has founded a cybersecurity agency that provides threat intel and security consulting services to small and medium-sized businesses. +Jacob is a cybersecurity consultant for organizations looking to secure their infrastructure. +He has founded a cybersecurity agency that provides threat intel and security consulting services to small and medium-sized businesses. -Jacob uses MISP to investigate threats and find IOCs. +Jacob uses MISP to investigate threats and find IOCs. He works with many clients and typically wants to integrate MISP into existing client solutions. _"There’s a difference between threat data and threat intelligence"_ @@ -213,7 +213,7 @@ Cyber Security consultant ### Jay _**The Inquisitor**_ -Jay is a risk analyst for a large technology company in the USA. +Jay is a risk analyst for a large technology company in the USA. He is responsible for identifying and predicting risks, as well as forecasting the cost of certain attacks to the organization. Jay uses MISP data to learn about the broad threat landscape and analyze the likelihood of certain risks, so as to gain situational awareness. @@ -269,7 +269,7 @@ Disinformation researcher and journalist #### Her objectives are to: - Distill essential information from a large piece of data, making it clear to the reader what really matters. -- Integrate MISP with TheHive for enhanced disinformation investigation and reporting. +- Integrate MISP with TheHive for enhanced disinformation investigation and reporting. - Verify that an article (or image, video, etc) doesn’t contain disinformation and verify that a source (publisher, domain, etc) doesn’t distribute disinformation. - Extend MISP for disinformation, adding object types for incidents and narratives, and using [AMITT](https://www.misp-project.org/galaxy.html#_misinformation_pattern) for attack patterns. @@ -279,10 +279,10 @@ Malcolm represents users that we care about but aren't so important to us. ### Malcolm _**The Data Expert**_ -Malcolm is a data scientist for a telecom operator in the USA. +Malcolm is a data scientist for a telecom operator in the USA. He assists the Security Operations Center with tasks related to anomaly detection, exploratory data analysis, data visualization, modeling, and optimization of security solutions. -Malcolm uses data from MISP alongside natural language processing, predictive modeling, and other data science techniques to assess, prioritize, and even predict risk. +Malcolm uses data from MISP alongside natural language processing, predictive modeling, and other data science techniques to assess, prioritize, and even predict risk. He can process threat data to help with alert prioritization and data-driven decision making. _"It is a mistake to theorize before one has data. Insensibly, one begins to twist facts to suit theories, instead of theories to suit facts"_ diff --git a/warninglists/README.md b/warninglists/README.md index 5d445ff..7596533 100644 --- a/warninglists/README.md +++ b/warninglists/README.md @@ -1,29 +1,29 @@ -# MISP warninglists -MISP warninglists are lists of well-known indicators that can be associated to potential false positives, errors or mistakes. -There is a Python module available to work with warninglists in a Pythonic way called [PyMISPWarningLists](https://github.com/MISP/PyMISPWarningLists). -[MISP warninglists GitHub Repo](https://github.com/MISP/misp-warninglists) +# MISP Warning Lists +MISP warning lists contain well-known indicators that may correspond to false positives, errors, or mistakes. +There is also a Python module for working with warning lists in a Pythonic way: [PyMISPWarningLists](https://github.com/MISP/PyMISPWarningLists). +[MISP Warning Lists GitHub Repository](https://github.com/MISP/misp-warninglists) -## MISP warning lists introduction: The dilemma of false-positive +## Warning Lists and False Positives -- False-positives are a common issue in threat intelligence sharing. - -- It’s often a contextual issue: - - False-positives might be different per community of users sharing -information. - - Organizations might have their own view on false-positives. +False positives are a common issue in threat intelligence sharing. +They are often contextual: +- What counts as a false positive may differ from one sharing community to another. +- Organizations may also have their own view of what should be treated as a false positive. ## Usage -By default MISP will only trigger hits for warninglists if the attribute IDS flag is set. This behaviour can be changed by setting the MISP config parameter MISP.warning_for_all to true. +By default, MISP triggers warning list hits only when the attribute IDS flag is set. +You can change this behavior by setting the `MISP.warning_for_all` configuration parameter to `true`. When an attribute matches a warninglist entry, an info/warning box is displayed at the event and attribute level, as can be seen in the screenshot below. ![Screenshot of event with one attribute that has warning list hits](./figures/warninglist-warnings.png) -Individual warninglists can be enabled or disabled at instance level using the warninglists index page. Examples of default warning lists are known public DNS resolvers, multicast IP addresses, hashes for empty values, rfc1918, TLDs or known google domains. +Individual warning lists can be enabled or disabled at the instance level from the warning lists index page. +Examples of default warning lists include known public DNS resolvers, multicast IP addresses, hashes for empty values, RFC1918 ranges, TLDs, and known Google domains. ![Screenshot of the warninglists index page](./figures/MISPwarninglist.png) -The warning lists can be expanded or added in JSON locally or via -pull requests (https://github.com/MISP/misp-warninglists). Warning lists can also be used for critical or core infrastructure or personally identifiable information. +Warning lists can be extended locally in JSON or contributed through pull requests to https://github.com/MISP/misp-warninglists. +They can also be used for critical infrastructure, core infrastructure, or personally identifiable information. ### Warninglists and data export The enforceWarninglist parameter of MISP restSearch can be used to exclude attributes that have a warninglist hit from the export. For more information on the MISP API, please refer to the [Automation and MISP API chapter](../sharing/). @@ -40,10 +40,11 @@ Alternatively, it is also possible to trigger an update using a CLI command. MISP/app/Console/cake Admin updateWarningLists ~~~ -If you are updating an existing warninglist, make sure you incremented the version number before triggering the update on the MISP. You can also contribute to the existing warninglists by forking [MISP warninglists GitHub Repo](https://github.com/MISP/misp-warninglists), making changes and then creating a pull request. +If you are updating an existing warning list, make sure you increment the version number before triggering the update in MISP. +You can also contribute to the existing warning lists by forking the [MISP Warning Lists GitHub Repository](https://github.com/MISP/misp-warninglists), making your changes, and then opening a pull request. ### Creating a custom warninglist 1. Create a new directory for your warninglist in /var/www/MISP/app/files/warninglists/lists. 2. Add a file called list.json to the newly created directory and add the content you want. You can use any of the existing warning lists in https://github.com/MISP/misp-warninglists as reference. 3. Trigger an update of the warning lists on the instance to load in your new warning list. -Example use cases are a list of domain names owned by you or your organisation or employee email addresses. +Example use cases include a list of domain names owned by your organization or a list of employee email addresses.