feat(*): Add context support and allow full length machine id prefix (#…

…32)

* feat(signals): Add context support for signal building helper

* feat(machine): Allow 48 characters for machine_id_prefix

* feat(*): Increment version number

* docs(*): Fix link and update machine_id_prefix description

* docs(*): Fix link

* test(script): Use dev env

.github/workflows/markdown.yml → .github/workflows/doc-links.yml

@@ -1,20 +1,25 @@
+name: Documentation links
+
 on:
   workflow_dispatch:
-
-name: Markdown files test and update
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
 
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
 
 jobs:
-  markdown-test-and-update:
-    name: Markdown files test and update
+  markdown-test-links:
+    name: Markdown test links
     runs-on: ubuntu-latest
     steps:
 
       - name: Clone sources
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           path: extension
 
@@ -34,12 +39,3 @@ jobs:
           cd extension
           awesome_bot --files README.md --allow-dupe --allow 401 --skip-save-results --white-list ddev.site --base-url http://localhost:8080/
           awesome_bot docs/*.md --skip-save-results --allow-dupe --allow 401 --white-list crowdsec.net/v2,ddev.site --base-url http://localhost:8080/docs/
-
-      - name: Generate table of contents
-        uses: technote-space/toc-generator@v4
-        with:
-          MAX_HEADER_LEVEL: 5
-          COMMIT_NAME: CrowdSec Dev Bot
-          TARGET_PATHS: 'docs/*.md'
-          CHECK_ONLY_DEFAULT_BRANCH: true
-          CREATE_PR: true

.github/workflows/release.yml

@@ -39,7 +39,7 @@ jobs:
           echo "VERSION_NUMBER=$(echo ${{ github.event.inputs.tag_name }} | sed 's/v//g' )" >> $GITHUB_ENV
 
       - name: Clone sources
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Check version ${{ env.VERSION_NUMBER }} consistency in files
         # Check src/Constants.php and CHANGELOG.md

.gitignore

@@ -13,4 +13,4 @@ composer-dev.*
 src/Storage/*.json
 
 # Integration test
-.enrollment_key.txt
+.enrollment_key.txt

CHANGELOG.md

@@ -8,6 +8,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The [public API](https://semver.org/spec/v2.0.0.html#spec-item-1) of this library consists of all public or protected methods, properties and constants belonging to the `src` folder.
 
+As far as possible, we try to adhere to [Symfony guidelines](https://symfony.com/doc/current/contributing/code/bc.html#working-on-symfony-code) when deciding whether a change is a breaking change or not.
+
+
+---
+
+## [3.2.0](https://github.com/crowdsecurity/php-capi-client/releases/tag/v3.2.0) - 2024-09-12
+[_Compare with previous release_](https://github.com/crowdsecurity/php-capi-client/compare/v3.1.0...v3.2.0)
+
+
+### Changed
+
+- Allow `machine_id_prefix` to have a length of 48 characters (full length of a machine ID)
+
+### Added
+
+- Add `context` support for Signals builder helper
+
 ---
 
 ## [3.1.0](https://github.com/crowdsecurity/php-capi-client/releases/tag/v3.1.0) - 2023-12-07

docs/DEVELOPER.md

@@ -10,21 +10,10 @@
 
 - [Local development](#local-development)
   - [DDEV setup](#ddev-setup)
-    - [DDEV installation](#ddev-installation)
-    - [Prepare DDEV PHP environment](#prepare-ddev-php-environment)
   - [DDEV Usage](#ddev-usage)
-    - [Use composer to update or install the lib](#use-composer-to-update-or-install-the-lib)
-    - [Unit test](#unit-test)
-    - [Integration test](#integration-test)
-    - [Coding standards](#coding-standards)
-      - [PHPCS Fixer](#phpcs-fixer)
-      - [PHPSTAN](#phpstan)
-      - [PHP Mess Detector](#php-mess-detector)
-      - [PHPCS and PHPCBF](#phpcs-and-phpcbf)
-      - [PSALM](#psalm)
-      - [PHP Unit Code coverage](#php-unit-code-coverage)
 - [Commit message](#commit-message)
   - [Allowed message `type` values](#allowed-message-type-values)
+- [Update documentation table of contents](#update-documentation-table-of-contents)
 - [Release process](#release-process)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -256,6 +245,25 @@ chmod +x .git/hooks/commit-msg
 - style (formatting; no production code change)
 - test (adding missing tests, refactoring tests; no production code change)
 
+
+## Update documentation table of contents
+
+To update the table of contents in the documentation, you can use [the `doctoc` tool](https://github.com/thlorenz/doctoc).
+
+First, install it:
+
+```bash
+npm install -g doctoc
+```
+
+Then, run it in the documentation folder:
+
+```bash
+doctoc docs/* --maxlevel 3  
+```
+
+
+
 ## Release process
 
 We are using [semantic versioning](https://semver.org/) to determine a version number. To verify the current tag, 

docs/USER_GUIDE.md

@@ -13,10 +13,6 @@
 - [Quick start](#quick-start)
   - [Installation](#installation)
   - [Watcher instantiation](#watcher-instantiation)
-    - [CAPI calls](#capi-calls)
-      - [Push signals](#push-signals)
-      - [Get Decisions stream list](#get-decisions-stream-list)
-      - [Enroll a watcher](#enroll-a-watcher)
 - [Watcher configurations](#watcher-configurations)
   - [Environment](#environment)
   - [Machine Id prefix](#machine-id-prefix)
@@ -25,22 +21,15 @@
   - [Scenarios](#scenarios)
   - [CAPI timeout](#capi-timeout)
   - [Metrics](#metrics)
-    - [Bouncer metrics](#bouncer-metrics)
-    - [Machine metrics](#machine-metrics)
 - [Storage implementation](#storage-implementation)
 - [Override the curl list handler](#override-the-curl-list-handler)
   - [Custom implementation](#custom-implementation)
   - [Ready to use `file_get_contents` implementation](#ready-to-use-file_get_contents-implementation)
 - [Example scripts](#example-scripts)
   - [Get decisions stream](#get-decisions-stream)
-    - [Command usage](#command-usage)
-    - [Example usage](#example-usage)
-  - [Push signals](#push-signals-1)
-    - [Command usage](#command-usage-1)
-    - [Example](#example)
-  - [Enroll a watcher](#enroll-a-watcher-1)
-    - [Command usage](#command-usage-2)
-    - [Example](#example-1)
+  - [Push signals](#push-signals)
+  - [Build and push one signal](#build-and-push-one-signal)
+  - [Enroll a watcher](#enroll-a-watcher)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -206,6 +195,10 @@ You have to pass 3 arrays as parameters for this method:
   - `message`: A human-readable message to add context for the alert. This is not required. Default to an empty message.
   - `start_at`: First event date for alert. This is not required. Default to `created_at` value.
   - `stop_at`: Last event date for alert. This is not required. Default to `created_at` value.
+  - `context`: An array of context key-value pairs. 
+    Each context array must have a `key` and `value` indexes: `[["key"=>"key1","value"=>"value1"],..., ["key"=>"keyN","value"=>"valueN"]]`.
+
+    This is not required. Default to an empty array.
 
 
 - An array `$source` with the following available keys:
@@ -287,7 +280,7 @@ This setting is not required.
 When you make your first call with a watcher, a `machine_id` will be generated and stored through your storage 
 implementation. This `machine_id` is a string of length 48 composed of characters matching the regular expression `#^[a-z0-9]+$#`.
 
-The `machine_id_prefix` setting allows to set a custom prefix to this `machine_id`. It must be a string matching the regular expression `#^[a-z0-9]{0,16}$#`. 
+The `machine_id_prefix` setting allows to set a custom prefix to this `machine_id`. It must be a string matching the regular expression `#^[a-z0-9]{0,48}$#`. 
 
 The final generated `machine_id` will still have a length of 48.
 
@@ -346,7 +339,7 @@ $configs = [
 This `scenarios` setting is required.
 
 You have to pass an array of CrowdSec scenarios that will be used to log in your watcher. 
-You should find a list of available scenarios on the [CrowdSec hub collections page](https://hub.crowdsec.net/browse/).
+You should find a list of available scenarios on the [CrowdSec hub collections page](https://app.crowdsec.net/hub).
 
 
 Each scenario must match the regular expression `#^[A-Za-z0-9]{0,16}\/[A-Za-z0-9_-]{0,64}$#`.
@@ -570,9 +563,25 @@ php tests/scripts/watcher/signals.php <SCENARIOS_JSON> <SIGNALS_JSON>
 #### Example
 
 ```bash
-php tests/scripts/watcher/signals.php '["crowdsecurity/http-backdoors-attempts", "crowdsecurity/http-bad-user-agent"]' '[{"message":"Ip 1.1.1.1 performed crowdsecurity/http-path-traversal-probing (6 events over 29.992437958s) at 2020-11-06 20:14:11.189255784 +0000 UTC m=+52.785061338","scenario":"crowdsecurity/http-path-traversal-probing","scenario_hash":"","scenario_version":"","source":{"id":1,"as_name":"TEST","cn":"FR","ip":"1.1.1.1","latitude":48.9917,"longitude":1.9097,"range":"1.1.1.1\/32","scope":"Ip","value":"1.1.1.1"},"start_at":"2020-11-06T20:13:41.196817737Z","stop_at":"2020-11-06T20:14:11.189252228Z"},{"message":"Ip 2.2.2.2 performed crowdsecurity/http-probing (6 events over 29.992437958s) at 2020-11-06 20:14:11.189255784 +0000 UTC m=+52.785061338","scenario":"crowdsecurity/http-probing","scenario_hash":"","scenario_version":"","source":{"id":2,"as_name":"TEST","cn":"FR","ip":"2.2.2.2","latitude":48.9917,"longitude":1.9097,"range":"2.2.2.2\/32","scope":"Ip","value":"2.2.2.2"},"start_at":"2020-11-06T20:13:41.196817737Z","stop_at":"2020-11-06T20:14:11.189252228Z"}]'
+php tests/scripts/watcher/signals.php '["crowdsecurity/http-backdoors-attempts", "crowdsecurity/http-bad-user-agent"]' '[{"message":"Ip 1.1.1.1 performed crowdsecurity/http-path-traversal-probing (6 events over 29.992437958s) at 2020-11-06 20:14:11.189255784 +0000 UTC m=+52.785061338","scenario":"crowdsecurity/http-path-traversal-probing","scenario_hash":"","scenario_version":"","source":{"id":1,"as_name":"TEST","cn":"FR","ip":"1.1.1.1","latitude":48.9917,"longitude":1.9097,"scope":"ip","value":"1.1.1.1"},"start_at":"2020-11-06T20:13:41.196817737Z","stop_at":"2020-11-06T20:14:11.189252228Z"},{"message":"Ip 2.2.2.2 performed crowdsecurity/http-probing (6 events over 29.992437958s) at 2020-11-06 20:14:11.189255784 +0000 UTC m=+52.785061338","scenario":"crowdsecurity/http-probing","scenario_hash":"","scenario_version":"","source":{"id":2,"as_name":"TEST","cn":"FR","ip":"2.2.2.2","latitude":48.9917,"longitude":1.9097,"scope":"ip","value":"2.2.2.2"},"start_at":"2020-11-06T20:13:41.196817737Z","stop_at":"2020-11-06T20:14:11.189252228Z","context":[{"key":"exampleKey1","value":"exampleValue1"}]}]'
+```
+
+### Build and push one signal
+
+#### Command usage
+
+```php
+php tests/scripts/watcher/build-and-push-one-signal.php <SCENARIOS_JSON> <SIGNAL_JSON>
+```
+
+#### Example
+
+```bash
+php tests/scripts/watcher/build-and-push-one-signal.php '["crowdsecurity/http-backdoors-attempts", "crowdsecurity/http-bad-user-agent"]' '{"message":"Ip 2.2.2.2 performed crowdsecurity/http-probing (6 events over 29.992437958s) at 2020-11-06 20:14:11.189255784 +0000 UTC m=+52.785061338","scenario":"crowdsecurity/http-probing","scenario_hash":"","scenario_version":"","source":{"id":2,"as_name":"TEST","cn":"FR","ip":"2.2.2.2","latitude":48.9917,"longitude":1.9097,"scope":"ip","value":"2.2.2.2"},"context":[{"key":"exampleKey1","value":"exampleValue1"}]}'
 ```
 
+
+
 ### Enroll a watcher
 
 #### Command usage

src/Client/AbstractClient.php

@@ -28,8 +28,8 @@ abstract class AbstractClient extends CommonAbstractClient
 
     public function __construct(
         array $configs,
-        CapiHandlerInterface $listHandler = null,
-        LoggerInterface $logger = null
+        ?CapiHandlerInterface $listHandler = null,
+        ?LoggerInterface $logger = null
     ) {
         $this->configs = $configs;
         $this->capiHandler = ($listHandler) ?: new Curl($this->configs);

src/Configuration/Signal.php

@@ -36,6 +36,7 @@ class Signal extends AbstractConfiguration
         'start_at',
         'stop_at',
         'uuid',
+        'context',
     ];
 
     /**
@@ -93,6 +94,14 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->thenInvalid('Invalid stop_at. Must match with ' . Constants::ISO8601_REGEX)
                 ->end()
             ->end()
+            ->arrayNode('context')
+                ->arrayPrototype()
+                    ->children()
+                        ->scalarNode('key')->isRequired()->cannotBeEmpty()->end()
+                        ->scalarNode('value')->isRequired()->end()
+                    ->end()
+                ->end()
+            ->end()
         ->end()
         ;
 

src/Configuration/Watcher.php

@@ -58,9 +58,9 @@ public function getConfigTreeBuilder(): TreeBuilder
             ->scalarNode('machine_id_prefix')
                 ->validate()
                 ->ifTrue(function (string $value) {
-                    return 1 !== preg_match('#^[a-z0-9]{0,16}$#', $value);
+                    return 1 !== preg_match('#^[a-z0-9]{0,48}$#', $value);
                 })
-                ->thenInvalid('Invalid machine id prefix. Length must be <= 16. Allowed chars are a-z0-9')
+                ->thenInvalid('Invalid machine id prefix. Length must be <= 48. Allowed chars are a-z0-9')
                 ->end()
             ->end()
             ->scalarNode('user_agent_suffix')

src/Constants.php

@@ -85,5 +85,5 @@ class Constants extends CommonConstants
     /**
      * @var string The current version of this library
      */
-    public const VERSION = 'v3.1.0';
+    public const VERSION = 'v3.2.0';
 }

src/Signal.php

@@ -26,15 +26,15 @@ class Signal
     /**
      * @var array
      */
-    private $properties;
+    private $decisions;
     /**
      * @var array
      */
-    private $source;
+    private $properties;
     /**
      * @var array
      */
-    private $decisions;
+    private $source;
 
     public function __construct(
         array $properties,
@@ -46,6 +46,21 @@ public function __construct(
         $this->configureDecisions($decisions);
     }
 
+    public function toArray(): array
+    {
+        return $this->properties + [
+            'decisions' => $this->decisions,
+            'source' => $this->source,
+        ];
+    }
+
+    private function configureDecisions(array $decisions): void
+    {
+        $configuration = new SignalDecisionsConfig();
+        $processor = new Processor();
+        $this->decisions = $processor->processConfiguration($configuration, [$configuration->cleanConfigs($decisions)]);
+    }
+
     private function configureProperties(array $properties): void
     {
         $configuration = new SignalConfig();
@@ -62,19 +77,4 @@ private function configureSource(array $source): void
         $processor = new Processor();
         $this->source = $processor->processConfiguration($configuration, [$configuration->cleanConfigs($source)]);
     }
-
-    private function configureDecisions(array $decisions): void
-    {
-        $configuration = new SignalDecisionsConfig();
-        $processor = new Processor();
-        $this->decisions = $processor->processConfiguration($configuration, [$configuration->cleanConfigs($decisions)]);
-    }
-
-    public function toArray(): array
-    {
-        return $this->properties + [
-            'decisions' => $this->decisions,
-            'source' => $this->source,
-        ];
-    }
 }