From 003d077a21fd9b08cb848bee119adfca874d4734 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 7 Jul 2025 14:47:37 +0100 Subject: [PATCH 1/3] enhance: One getting started and move around resources --- .../docs/getting_started/getting_started.md | 79 ---------- .../docs/getting_started/install.mdx | 104 ------------- .../docs/getting_started/install_freebsd.md | 145 ------------------ .../docs/getting_started/install_softagent.md | 2 +- crowdsec-docs/docs/getting_started/intro.md | 27 ---- .../docs/getting_started/sdk_intro.mdx | 21 +++ crowdsec-docs/docusaurus.config.js | 34 +++- crowdsec-docs/sidebars.js | 98 +++--------- .../getting_started/installation/windows.mdx | 2 +- .../getting_started/introduction.mdx | 12 ++ 10 files changed, 80 insertions(+), 444 deletions(-) delete mode 100644 crowdsec-docs/docs/getting_started/getting_started.md delete mode 100644 crowdsec-docs/docs/getting_started/install.mdx delete mode 100644 crowdsec-docs/docs/getting_started/install_freebsd.md delete mode 100644 crowdsec-docs/docs/getting_started/intro.md create mode 100644 crowdsec-docs/docs/getting_started/sdk_intro.mdx diff --git a/crowdsec-docs/docs/getting_started/getting_started.md b/crowdsec-docs/docs/getting_started/getting_started.md deleted file mode 100644 index 2aa6b14f4..000000000 --- a/crowdsec-docs/docs/getting_started/getting_started.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -id: getting_started -title: Getting Started ---- - -import AcademyPromo from '@site/src/components/AcademyPromo'; - -Welcome to CrowdSec! - -In this section, you'll be taken through the process of creating a console account, with the initial step being the installation of the Security Engine, followed by the deployment of your first Remediation Component. - -## Creating a console account - -To embark on your CrowdSec journey, the optimal starting point is to set up a console account, as it grants you access to complimentary features that seamlessly integrate with your Security Engine. - -The CrowdSec console serves as a web-based interface enabling you to conveniently monitor all your CrowdSec instances from a centralized hub. To get started, simply [sign up here](https://app.crowdsec.net/signup). - - -## Deploy - -### Walkthrough - -If you prefer a guided, step-by-step video tutorial for installing the Security Engine in a sandbox environment, please refer to our comprehensive guide. - - - - - -or follow the steps below. - -### Security Engine - -:::info -In our updated documentation, we now refer to CrowdSec as the "Security Engine" and Bouncers as "Remediation Components" to better describe their roles in the ecosystem. -::: - -#### Prerequisites - -The Security Engine by default uses the following ports: - - 8080/tcp for the API - - 6060/tcp for the Prometheus metrics / Debugging - -If these ports are not available on your system, you can change them in the configuration file post installation. See [Configuration](/configuration/crowdsec_configuration.md) for more information. - -Please note that the API is mandatory for your security engine, do not remove it from your configuration. - -#### Using the repository - -For the most straightforward installation of the Security Engine, utilize the official repository, guaranteeing you'll constantly have the latest version. - -Please see the relevant documentation for your OS: -- [Linux](/getting_started/install.mdx) -- [FreeBSD](/getting_started/install_freebsd.md) -- [Windows](/getting_started/getting_started_on_windows.md) - -#### Installing from source - -Should you opt for a source-based installation, you can follow the steps outlined [here](/getting_started/install_source.mdx). - - -### Remediation Component - -After installing the Security Engine, you can proceed to install a Remediation Component, which is responsible for executing actions based on the decisions made by the Security Engine. - -The specific Remediation Component to install may vary based on your network and operating system configuration. - -If you are uncertain about which one to install, please refer to our [Remediation Components](/u/bouncers/intro) section or join our [Discord](https://discord.gg/crowdsec) and ask our community. - -## Enroll - -Since you created your account on the CrowdSec console, you can now [enroll your Security Engine to your account](https://app.crowdsec.net/security-engines?enroll-engine=true). - -To do so, you can find steps outlined [here](/u/getting_started/post_installation/console/#engines-page). \ No newline at end of file diff --git a/crowdsec-docs/docs/getting_started/install.mdx b/crowdsec-docs/docs/getting_started/install.mdx deleted file mode 100644 index 2e917960f..000000000 --- a/crowdsec-docs/docs/getting_started/install.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -id: install_crowdsec -title: Linux -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -For those that prefer hands-on approach, you can as well [manually install crowdsec](/getting_started/install_source.mdx). - -## Install our repositories - -Installing our repositories allows you to access the latest packages of the Security Engine and Remediation Components. - -:::info -We are using [packagecloud.io service](https://packagecloud.io/crowdsec/crowdsec/). -While `curl | sudo shell` can be convenient for some, [alternative installation methods are available](https://packagecloud.io/crowdsec/crowdsec/install#manual). -::: - -```bash -curl -s https://install.crowdsec.net | sudo sh -``` - - -## Install the Security Engine - -Before installing the package, you might want to check [the ports that will be used](/docs/next/configuration/network_management). - - - - apt install crowdsec - - - - yum install crowdsec - - - - dnf install crowdsec - - - - zypper install crowdsec - - - - opkg install crowdsec - - - - yum install crowdsec - - - -You now have the Security Engine running ! You can move forward and install a [remediation component](/u/bouncers/intro), or take a [tour](/getting_started/crowdsec_tour.mdx) of the software beforehand ! - -Directories: - -* The application lives in the folder `/etc/crowdsec`. -* The data is stored in the folder `/var/lib/crowdsec/data`. - - -## Remediation Component - -:::caution - -Keep in mind that a CrowdSec package is only in charge of the "detection", and won't block anything on its own. -You need to deploy a [Remediation Component](/u/bouncers/intro) to enforce decisions. - -::: - -## Enrolling your instance - -The next step is to enroll your instance with the [CrowdSec Console](https://app.crowdsec.net/security-engines?enroll-engine=true). - -For the benefits, please visit the [Console section](/u/console/intro). - -## Running CrowdSec on Raspberry Pi OS/Raspbian - -Please keep in mind that Raspberry Pi OS is designed to work on all -Raspberry Pi versions. Even if the port target is known as armhf, it's -not exactly the same target as the debian named armhf port. - -The best way to have a CrowdSec version for such an architecture is to -do: - -1. install golang (all versions from 1.20 will do) -2. `export GOARCH=arm` -3. `export CGO=1` -4. Update the GOARCH variable in the Makefile to `arm` -5. install the arm gcc cross compiler (On debian the package is gcc-arm-linux-gnueabihf) -6. Compile CrowdSec using the usual `make` command diff --git a/crowdsec-docs/docs/getting_started/install_freebsd.md b/crowdsec-docs/docs/getting_started/install_freebsd.md deleted file mode 100644 index f1a214417..000000000 --- a/crowdsec-docs/docs/getting_started/install_freebsd.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: install_crowdsec_freebsd -title: FreeBSD -sidebar_position: 1 ---- - -## Configuring the repositories - -FreeBSD packages are available in the official repositories. - -By default, the command `pkg install` should use the quarterly releases (January, April, July and October, updated with security fixes). - -You can check `/etc/pkg/FreeBSD.conf` and [change **quarterly** to **latest**](https://wiki.freebsd.org/Ports/QuarterlyBranch) if you feel comfortable upgrading your system. - - -## Install the Security Engine - -Before installing the package, you might want to check [the ports that security engine will use](/docs/next/configuration/network_management). - -The CrowdSec package itself can be installed with: - -```shell -$ sudo pkg install crowdsec -``` - -If the command installs the legacy v1.1.1, you will have a couple more steps to do, please have a look at the [related blog post](https://docs.crowdsec.net/blog/crowdsec_firewall_freebsd/). - -You'll see a message that tells you how to activate the agent: - -```shell -$ sudo sysrc crowdsec_enable="YES" -crowdsec_enable: -> YES -$ sudo service crowdsec start -Fetching hub inventory -INFO[21-12-2021 03:13:35 PM] Wrote new 197364 bytes index to /usr/local/etc/crowdsec/hub/.index.json -[...] -``` - -The service registers itself with the Central API on crowdsec.net, updates the plugin registry and downloads the "crowdsecurity/freebsd" collection of plugins. -This includes, for instance, a parsers for sshd logs and a database to correlate IP addresses with geographical information. - -As opposed to its Linux counterparts, the FreeBSD package does not automatically detect the software that is running on the machine; please refer -to our documentation to add parsers, scenarios and more. - -:::caution -Keep in mind that the crowdsec package is only in charge of the "detection", and won't block anything on its own. -You need to deploy a [bouncer](/u/bouncers/intro) to "apply" decisions. -::: - - -If all this sounds confusing, it might be a good moment to take a [tour](/getting_started/crowdsec_tour.mdx) of the software before continuing. - -## Installing the firewall remediation component - -This is a package that receives decisions to ban IP addresses and whole address ranges, if they are the source of verified attacks. - -To install and enable it: - -```shell -$ sudo pkg install crowdsec-firewall-bouncer -[...] -$ sudo sysrc crowdsec_firewall_enable=YES -crowdsec_firewall_enable: -> YES -$ sudo service crowdsec_firewall start -Registered: cs-firewall-bouncer-ZjpcXlUx -``` - - -The firewall remediation component is now running. It applies rules via the [Packet Filter](https://docs.freebsd.org/en/books/handbook/firewalls/#firewalls-pf). - -Create the required tables by creating or appending this to `/etc/pf.conf`: - -``` -table persist -table persist -block drop in quick from to any -block drop in quick from to any -``` - -If Packet Filter is not enabled, you can do it now: - -```shell -$ sudo sysrc pf_enable=YES -pf_enable: NO -> YES -$ sudo service pf start -Enabling pf. -``` - -Reload the rules with: - -```shell -$ sudo pfctl -f /etc/pf.conf -``` - -You can check the configuration with: - -```shell -$ sudo pfctl -sr -block drop in quick from to any -block drop in quick from to any -$ sudo service pf check -Checking pf rules. -$ sudo service pf status -Status: Enabled for 0 days 00:00:02 Debug: Urgent -[...] -``` - -:::info -While we are suggesting the most common firewall bouncer, check our [hub](https://hub.crowdsec.net) for more of them. -Find a bouncer directly for your application ([nginx](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-nginx-bouncer), [php](https://github.com/crowdsecurity/php-cs-bouncer), [wordpress](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-wordpress-bouncer)) or your providers ([cloudflare](https://hub.crowdsec.net/author/crowdsecurity/bouncers/cs-cloudflare-bouncer), [AWS/GCP/...](https://hub.crowdsec.net/author/fallard84/bouncers/cs-cloud-firewall-bouncer)) -::: - - -## Building from sources - -Another option - and the only one if you have a [Tier-2 or unsupported platform](https://www.freebsd.org/platforms/) whose binaries are harder to find -or seldom updated - is to build the packages yourself by using our FreeBSD ports. - -If you are not familiar with how ports work, be aware that mixing ports and binary packages might break your system. -Please read [the FreeBSD documentation](https://docs.freebsd.org/en/books/handbook/ports/#ports-using) and decide for yourself if it's the best method for your case. - -If you are already familiar with ports, running `make install` in `/usr/ports/security/crowdsec` and `/usr/ports/security/crowdsec-firewall-bouncer` -will compile and install the packages and all their dependencies. Then configure them as you would normally do with `pkg install`. - - -## Troubleshooting - -In some cases, CrowdSec is unable to generate the machine id and is unable to initialize properly. - -We saw it happen with an APU board, likely due to the open source coreboot firmware. - -Start `hostid` and `hostid_save`: - -``` -/etc/rc.d/hostid start -/etc/rc.d/hostid_save start -``` - -Then start again the CrowdSec' service `service crowdsec start`. - -## Enrolling your instance - -The next step is to enroll your instance with the [CrowdSec Console](https://app.crowdsec.net/security-engines?enroll-engine=true). - -For the benefits, please visit the [Console section](/u/console/intro). \ No newline at end of file diff --git a/crowdsec-docs/docs/getting_started/install_softagent.md b/crowdsec-docs/docs/getting_started/install_softagent.md index 1823f3d9e..191afe393 100644 --- a/crowdsec-docs/docs/getting_started/install_softagent.md +++ b/crowdsec-docs/docs/getting_started/install_softagent.md @@ -4,7 +4,7 @@ title: Soft Agent sidebar_position: 1 --- -# Using our SDK +# Using our PHP SDK With the help of our SDK, If you are developing security software that detects misbehaviors and does remediation on IPs, you can send signals about your detections and benefit from the community blocklist. diff --git a/crowdsec-docs/docs/getting_started/intro.md b/crowdsec-docs/docs/getting_started/intro.md deleted file mode 100644 index f8af6f022..000000000 --- a/crowdsec-docs/docs/getting_started/intro.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: security_engine_intro -title: Introduction -sidebar_position: 1 ---- - -# Security Engine - -:::info -You may see Security Engine referred to as "agent" in the documentation/videos and "machines" within cscli commands. -::: - -The Security Engine is a core component of CrowdSec. It is the component that will analyze logs and will expose an API endpoint for the remediation components to get the decisions made by the engine. - -## Supported Platforms - -See [Version Matrix](/getting_started/versions_matrix.md) for a list of supported platforms. - -## Why is my Security Engine classed as a "log processor" within the console? - -The `Security Engine` comes compiled with a number of core components that can be enabled or disabled at runtime. -One of these features is called the **"LAPI"** (Local API) and other one is the **"log processor"**. - -A single `Security Engine` can run in autonomous mode where it handles reading logs (or requests) and processing them as well as handling alerts and other task on its own **"LAPI"**. -For **scaling** or **perimeter segmentation** reasons you might want to have a distributed setup. In that case multiple `Security Engines` process logs and send alerts to a central one's **"LAPI"**. In that distributed case you'll see **"log processors"** attached to the central `Security Engines` in the console UI. - -Read more about the [Log Processor](log_processor/intro.mdx) and the [Local API](local_api/intro.md). diff --git a/crowdsec-docs/docs/getting_started/sdk_intro.mdx b/crowdsec-docs/docs/getting_started/sdk_intro.mdx new file mode 100644 index 000000000..04679bd9e --- /dev/null +++ b/crowdsec-docs/docs/getting_started/sdk_intro.mdx @@ -0,0 +1,21 @@ +--- +id: sdk_intro +title: introduction to the SDKs +sidebar_position: 1 +--- + +CrowdSec offers lightweight SDKs for Python and PHP to help developers seamlessly integrate signal sharing capabilities into their security tools, platforms, or services. + +By using these SDKs, you can report signals such as suspicious IP activity or confirmed attacks directly to the Central API (CAPI). In return, your users gain access to the CrowdSec Community Blocklist, a curated and constantly updated list of IPs involved in malicious behavior observed across the global CrowdSec network. + +Why Integrate the SDK: +- **Simple Integration** — Add signal sharing with just a few lines of code +- **Community-Powered Protection** — Contributions help power our global threat intelligence network +- **Mutual Benefit** — Your platform shares valuable intelligence and gains stronger real-time protection in return + +## Supported SDKs + +* [Python SDK](install_pyagent) +* [PHP SDK](install_softagent) + +Whether you're building a WAF, SIEM, or a custom security tool, the CrowdSec SDKs make it easy to contribute to and benefit from a collaborative defense network. diff --git a/crowdsec-docs/docusaurus.config.js b/crowdsec-docs/docusaurus.config.js index 6d6e29a05..5e570e4ac 100644 --- a/crowdsec-docs/docusaurus.config.js +++ b/crowdsec-docs/docusaurus.config.js @@ -138,8 +138,9 @@ module.exports = { label: "Cscli", }, { - to: "/u/user_guides/intro", - label: "Guides", + type: "doc", + label: "SDK", + docId: "getting_started/sdk_intro", }, ], }, @@ -168,13 +169,22 @@ module.exports = { label: "Console", }, { - to: `https://academy.crowdsec.net/courses?${ - process.env.NODE_ENV === "production" - ? "utm_source=docs&utm_medium=menu&utm_campaign=top-menu&utm_id=academydocs" - : "" - }`, - label: "Academy", + label: "Resources", position: "left", + items: [ + { + to: "/u/user_guides/intro", + label: "Guides", + }, + { + to: `https://academy.crowdsec.net/courses?${ + process.env.NODE_ENV === "production" + ? "utm_source=docs&utm_medium=menu&utm_campaign=top-menu&utm_id=academydocs" + : "" + }`, + label: "Academy", + }, + ], }, { to: "/u/troubleshooting/intro", @@ -326,6 +336,14 @@ module.exports = { from: "/docs/next/faq", to: "/u/troubleshooting/intro", }, + { + from: "/docs/next/getting_started/install_crowdsec", + to: "/u/getting_started/installation/linux", + }, + { + from: "/docs/next/getting_started/install_crowdsec_freebsd", + to: "/u/getting_started/installation/freebsd", + }, ], }, ], diff --git a/crowdsec-docs/sidebars.js b/crowdsec-docs/sidebars.js index 48a0dbaee..b1a4703cb 100644 --- a/crowdsec-docs/sidebars.js +++ b/crowdsec-docs/sidebars.js @@ -3,92 +3,32 @@ module.exports = { // By default, Docusaurus generates a sidebar from the docs folder structure //tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], // But you can create a sidebar manually + sdkSideBar: [ + { + type: "doc", + label: "Introduction", + id: "getting_started/sdk_intro", + }, + { + type: "doc", + label: "Python", + id: "getting_started/install_pyagent", + }, + { + type: "doc", + label: "PHP", + id: "getting_started/install_softagent", + }, + ], tutorialSidebar: [ { type: "doc", id: "intro", }, { - type: "category", + type: "link", label: "Getting Started", - collapsed: false, - link: { - type: "doc", - id: "getting_started/getting_started", - }, - items: [ - { - type: "category", - label: "Security Engine", - collapsed: true, - link: { - type: "doc", - id: "getting_started/security_engine_intro", - }, - items: [ - "getting_started/install_crowdsec", - "getting_started/install_crowdsec_freebsd", - "getting_started/install_crowdsec_opnsense", - "getting_started/install_crowdsec_pfsense", - "getting_started/install_windows", - { - type: "link", - label: "Helm/K8s", - href: "https://artifacthub.io/packages/helm/crowdsec/crowdsec", - }, - { - type: "category", - label: "Container", - items: [ - { - type: "link", - href: "https://hub.docker.com/r/crowdsecurity/crowdsec", - label: "Docker Hub", - }, - { - type: "link", - href: "https://github.com/crowdsecurity/crowdsec/pkgs/container/crowdsec", - label: "GHCR", - }, - { - type: "link", - href: "https://github.com/crowdsecurity/example-docker-compose", - label: "Examples", - }, - ], - }, - "getting_started/install_source", - ], - }, - { - type: "link", - label: "Remediation", - href: "/u/bouncers/intro", - }, - { - type: "ref", - id: "appsec/intro", - label: "AppSec", - }, - { - type: "category", - label: "SDK", - items: [ - { - type: "doc", - label: "Python", - id: "getting_started/install_pyagent", - }, - { - type: "doc", - label: "PHP", - id: "getting_started/install_softagent", - }, - ], - }, - "getting_started/crowdsec_tour", - "getting_started/versions_matrix", - ], + href: "/u/getting_started/intro", }, { type: "doc", diff --git a/crowdsec-docs/unversioned/getting_started/installation/windows.mdx b/crowdsec-docs/unversioned/getting_started/installation/windows.mdx index 17e6753d3..022ebb1f4 100644 --- a/crowdsec-docs/unversioned/getting_started/installation/windows.mdx +++ b/crowdsec-docs/unversioned/getting_started/installation/windows.mdx @@ -53,4 +53,4 @@ choco install crowdsec-windows-firewall-bouncer ## Next Steps? -Great, you now have CrowdSec installed on your system. Within the [post installation steps](/getting_started/next_steps.mdx) you will find the next steps to configure and optimize your installation. +Great, you now have CrowdSec installed on your system. Within the [post installation steps](/getting_started/next_steps.mdx) you will find the next steps to configure and optimize your installation. You can also checkout the [detailed documentation](/docs/next/getting_started/install_windows) to find specific information on configuring for IIS and windows firewall. diff --git a/crowdsec-docs/unversioned/getting_started/introduction.mdx b/crowdsec-docs/unversioned/getting_started/introduction.mdx index b6788a4e5..dd9e3bc5e 100644 --- a/crowdsec-docs/unversioned/getting_started/introduction.mdx +++ b/crowdsec-docs/unversioned/getting_started/introduction.mdx @@ -4,6 +4,7 @@ title: Introduction sidebar_position: 1 --- +import AcademyPromo from '@site/src/components/AcademyPromo'; import useBaseUrl from "@docusaurus/useBaseUrl" import UnderlineTooltip from "@site/src/components/UnderlineTooltip" @@ -82,5 +83,16 @@ CrowdSec Security Engine uses the following default ports (bound to localhost/lo * 6060/tcp: Prometheus metrics port * 8080/tcp: API port +## Resources + + + + From 020b4056cd076e94a47035db3955153750683dbc Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 9 Jul 2025 14:38:51 +0100 Subject: [PATCH 2/3] enhance: fix --- crowdsec-docs/unversioned/getting_started/introduction.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crowdsec-docs/unversioned/getting_started/introduction.mdx b/crowdsec-docs/unversioned/getting_started/introduction.mdx index 11ffe3d60..854bf45fd 100644 --- a/crowdsec-docs/unversioned/getting_started/introduction.mdx +++ b/crowdsec-docs/unversioned/getting_started/introduction.mdx @@ -4,7 +4,7 @@ title: Introduction sidebar_position: 1 --- -import AcademyPromo from '@site/src/components/AcademyPromo'; +import AcademyPromo from '@site/src/components/academy-promo'; import useBaseUrl from "@docusaurus/useBaseUrl" import UnderlineTooltip from "@site/src/components/underline-tooltip" From db32fd1157310a3b3035e6e0e1e1c844984514ba Mon Sep 17 00:00:00 2001 From: Laurence Date: Wed, 9 Jul 2025 14:41:33 +0100 Subject: [PATCH 3/3] enhance: merge fixes --- crowdsec-docs/docusaurus.config.ts | 4 +-- .../components/remediation-support-badge.tsx | 26 ++++++++++--------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/crowdsec-docs/docusaurus.config.ts b/crowdsec-docs/docusaurus.config.ts index 46e2bef58..73cbeea32 100644 --- a/crowdsec-docs/docusaurus.config.ts +++ b/crowdsec-docs/docusaurus.config.ts @@ -104,9 +104,7 @@ const NAVBAR_ITEMS: NavbarItem[] = [ label: "Guides", }, { - to: `https://academy.crowdsec.net/courses?${ - process.env.NODE_ENV === "production" ? "utm_source=docs&utm_medium=menu&utm_campaign=top-menu&utm_id=academydocs" : "" - }`, + to: ACADEMY_URL, label: "Academy", }, ], diff --git a/crowdsec-docs/src/components/remediation-support-badge.tsx b/crowdsec-docs/src/components/remediation-support-badge.tsx index c83d10329..434041fbf 100644 --- a/crowdsec-docs/src/components/remediation-support-badge.tsx +++ b/crowdsec-docs/src/components/remediation-support-badge.tsx @@ -14,18 +14,20 @@ const RemediationSupportBadge = ({ title, description, support }: { title: strin //ugly, for test const colorClass = support === "Unsupported" ? "bg-red-400" : "bg-green-400"; return ( - - -
- {title} - {support} -
- - -

{description}

- - - + + + +
+ {title} + {support} +
+ + +

{description}

+ + + + ); };