### Pro License Detection

Source: https://context7.com/juliopotier/secupress/llms.txt

Check if the SecuPress Pro add-on is installed and licensed, and determine if specific features are restricted to Pro users. Also shows how to retrieve license details.

```php
// Is Pro plugin present (regardless of license validity)?
if ( secupress_has_pro() ) {
    echo 'SecuPress Pro plugin is installed.';
}

// Is Pro installed AND licensed?
if ( secupress_is_pro() ) {
    echo 'SecuPress Pro is fully activated.';
}

// Check if a specific settings field is Pro-gated
if ( secupress_feature_is_pro( 'login-protection_sessions_control' ) ) {
    echo 'Session Control requires SecuPress Pro.';
}

// Check Pro license validity directly
if ( secupress_has_pro_license() ) {
    $key = secupress_get_consumer_key();
    $email = secupress_get_consumer_email();
}
```

--------------------------------

### User and Capability Utilities

Source: https://context7.com/juliopotier/secupress/llms.txt

Look up users by various fields, validate WP_User objects, and determine the required capability to access SecuPress pages. Includes an example of overriding the default capability.

```php
// Look up a user by ID, email, login, nicename, or display name
$user = secupress_get_user_by( 42 );            // by ID
$user = secupress_get_user_by( 'jane@example.com' ); // by email
$user = secupress_get_user_by( 'janedoe' );     // by login / nicename / display_name

if ( false === $user ) {
    echo 'User not found.';
}

// Validate that something is a real WP_User
$valid = secupress_is_user( $user );         // bool
$user  = secupress_is_user( $user, true );   // returns WP_User or false

// Get the required capability to access SecuPress pages
$cap = secupress_get_capability(); // 'manage_network_options' on multisite, 'administrator' on single
if ( current_user_can( $cap ) ) {
    // show SecuPress UI
}

// Override the required capability
add_filter( 'secupress.user_capability', function( $role, $context ) {
    return 'manage_options'; // allow site admins on multisite sub-sites
}, 10, 2 );

// Check if current site is full HTTPS
$is_https = secupress_site_is_using_https( 'both' ); // 'both', 'site', or 'home'
```

--------------------------------

### Get and Validate IP Addresses with SecuPress

Source: https://context7.com/juliopotier/secupress/llms.txt

Retrieve the current visitor's IP address and validate IP strings, supporting wildcard and CIDR formats. You can also override the IP source using a filter.

```php
// Get current visitor IP (reads REMOTE_ADDR only, Cloudflare-safe via filter)
$ip = secupress_get_ip();
```

```php
// Override IP source (e.g., behind a trusted proxy)
add_filter( 'secupress.ip.get_ip', function( $ip ) {
    if ( ! empty( $_SERVER['HTTP_X_REAL_IP'] ) ) {
        return $_SERVER['HTTP_X_REAL_IP'];
    }
    return $ip;
} );
```

```php
// Validate a plain IP
$valid = secupress_ip_is_valid( '192.168.1.1' ); // true
```

```php
// Validate an IPv4 wildcard range
$valid = secupress_ip_is_valid( '192.168.*', true ); // true
```

```php
// Validate CIDR notation
$valid = secupress_ip_is_valid( '10.0.0.0/24', true ); // true
```

```php
// Validate only IPv4
$valid = secupress_ip_is_valid( '192.168.1.1', false, FILTER_FLAG_IPV4 ); // true
```

```php
// Check if the server is running SSL (Cloudflare-compatible)
$is_ssl = secupress_server_is_ssl(); // true / false
```

--------------------------------

### Get Module Registry and Check Sub-module Status

Source: https://context7.com/juliopotier/secupress/llms.txt

Retrieve the complete list of modules and their sub-modules, or check if a specific sub-module is active. Also includes functions to check if a sub-module is Pro-only and to generate admin URLs.

```php
// Get the complete module map
$modules = secupress_get_modules();
foreach ( $modules as $slug => $data ) {
    echo $slug . ': ' . $data['title'] . PHP_EOL;
}
/*
welcome: Dashboard
users-login: Users & Login
plugins-themes: Plugins & Themes
wordpress-core: WordPress Core
sensitive-data: Sensitive Data
firewall: Firewall & GeoIP
file-system: Malware Scanners
ssl: SSL & HTTPS
antispam: Spam & Phishing
logs: Logs and IPs
backups: Backups
alerts: Alerts & Notifications
schedules: Schedules
addons: Add-ons
services: Security Services
*/

// Check if a specific sub-module is running
if ( secupress_is_submodule_active( 'sensitive-data', 'blackhole' ) ) {
    echo 'Blackhole trap is active';
}

// Get all currently active sub-modules grouped by parent module
$active = secupress_get_active_submodules();
// ['users-login' => ['move-login', 'captcha'], 'firewall' => ['bbq-headers'], ...]

// Check if a sub-module is Pro-only
$is_pro = secupress_submodule_is_pro( 'users-login', 'double-auth' ); // true

// Generate a SecuPress admin page URL
$url = secupress_admin_url( 'modules', 'users-login' );
// → admin.php?page=secupress_modules&module=users-login
```

--------------------------------

### Get security grade and counters

Source: https://context7.com/juliopotier/secupress/llms.txt

Use secupress_get_scanner_counts() to retrieve aggregated scan results, including counts for 'good', 'warning', 'bad', and 'notscannedyet' statuses, along with the overall security grade and percentage.

```php
// Get the security grade and counters
$counts = secupress_get_scanner_counts();
/*
[
  'good'          => 28,
  'warning'       => 3,
  'bad'           => 4,
  'notscannedyet' => 0,
  'total'         => 35,
  'percent'       => 80,
  'grade'         => 'B',
  'letter'        => '<span class="letter lB ...">B</span>',
  'text'          => 'Almost perfect!',
  'subtext'       => 'Your grade is B with 28 good scanned items.',
  'color'         => '241,196,15',
]
*/
```

--------------------------------

### Get all scanner groups and test names

Source: https://context7.com/juliopotier/secupress/llms.txt

Use secupress_get_scanners() to retrieve a map of all security test identifiers grouped by module. This is useful for understanding the available security checks.

```php
// List all scanner groups and test names
$tests = secupress_get_scanners();
/*
[
  'users-login'    => ['Admin_User', 'Easy_Login', 'Subscription', ...],
  'plugins-themes' => ['Plugins_Update', 'Themes_Update', 'Bad_Old_Plugins', ...],
  'wordpress-core' => ['Core_Update', 'Auto_Update', 'Bad_Old_Files', ...],
  'sensitive-data' => ['Discloses', 'Readme_Discloses', 'HTTPS', ...],
  'file-system'    => ['Chmods', 'Directory_Listing', 'Malware_Scanners', ...],
  'firewall'       => ['Shellshock', 'Bad_User_Agent', 'PhpVersion', 'Php_404'],
]
*/
```

--------------------------------

### Get Available Malware Scanners and Scan Status

Source: https://context7.com/juliopotier/secupress/llms.txt

Retrieve a list of available malware scan engines with their metadata for UI rendering. Also, check the timestamp of the last malware scan.

```php
$scanners = secupress_get_malware_scanners();
/*
[ 
  ['icon' => 'radar',     'file' => 'malware_keywords',  'name' => 'Malware Scanner',            ...],
  ['icon' => 'data-base', 'file' => 'malware_keywords_db','cback' => 'secupress_get_database_scanner', 'name' => 'Database Scanner', ...],
  ['icon' => 'cog',       'file' => 'tag_attr',           'cback' => 'secupress_get_content_spam_scanner', 'name' => 'SEO Poisoning Scanner', ...],
  ['icon' => 'core',                                       'cback' => 'secupress_file_scanner_get_full_filetree', 'name' => 'WordPress Core Files Integrity', ...],
]
*/
```

```php
// Check when the last malware scan ran
$last_scan = secupress_get_malware_scan_last_time(); // Unix timestamp or 0
if ( $last_scan > 0 ) {
    echo 'Last scan: ' . date( 'Y-m-d H:i', $last_scan );
}
```

--------------------------------

### Get human-readable title for an attack type

Source: https://context7.com/juliopotier/secupress/llms.txt

Convert an attack type identifier (e.g., 'loginattempts') into a human-readable title using secupress_attacks_get_type_title().

```php
// Get human-readable title for an attack type
$title = secupress_attacks_get_type_title( 'loginattempts' ); // "Login Attempts"
$title = secupress_attacks_get_type_title( 'xmlrpc' );        // "XMLRPC Intrusions"
// Other types: ban_ip, plugins, theme, zipfile, move_login,
//              passwordspraying, users, bad_robots, bad_request_content, honeypot
```

--------------------------------

### Read/Write Top-Level SecuPress Options

Source: https://context7.com/juliopotier/secupress/llms.txt

Use `secupress_get_option()` to read a specific option and `secupress_set_option()` to write a single option. For bulk updates, retrieve all options using `get_site_option()`, modify the array, and then use `secupress_update_options()`.

```php
// Read the consumer API key (returns false if not set)
$key = secupress_get_option( 'consumer_key' );

// Override via filter (useful for mu-plugins or hosting panels)
add_filter( 'pre_secupress_get_option_consumer_key', function( $pre, $default ) {
    return 'MY-HARDCODED-KEY';
}, 10, 2 );

// Write a single option
secupress_set_option( 'site_is_pro', 1 );

// Bulk-write multiple options at once
$options = get_site_option( SECUPRESS_SETTINGS_SLUG, [] );
$options['consumer_email'] = 'admin@example.com';
$options['consumer_key']   = 'ABCD-1234';
secupress_update_options( $options );
```

--------------------------------

### Manage Server Rules with SecuPress

Source: https://context7.com/juliopotier/secupress/llms.txt

Write or remove named marker sections in `.htaccess` (Apache), `web.config` (IIS7), or display manual-edit instructions for Nginx. A high-level helper handles cross-server compatibility.

```php
// Write custom rules to .htaccess under a unique marker
$rules = "RewriteRule ^wp-login-old\.php - [F,L]\n";
$ok = secupress_write_htaccess( 'Block-Old-Login', $rules );
// Creates: # BEGIN SecuPress Block-Old-Login … # END SecuPress
```

```php
// Remove the rules (pass empty/false)
secupress_write_htaccess( 'Block-Old-Login' );
```

```php
// High-level module helper (handles Apache / IIS7 / Nginx automatically)
secupress_add_module_rules_or_notice( [
    'marker'   => 'bad-user-agents',
    'rules'    => "RewriteCond %{HTTP_USER_AGENT} ^(curl|wget) [NC]\nRewriteRule .* - [F,L]\n",
    'iis_args' => [],
    'title'    => 'Block Bad User Agents',
] );
```

```php
// Remove rules and show an admin notice if not writable
secupress_remove_module_rules_or_notice( 'bad-user-agents', 'Block Bad User Agents' );
```

```php
// Filter Nginx notice display
add_filter( 'secupress.nginx.notice', '__return_false' ); // suppress nginx notice
```

--------------------------------

### Read/Write Module-Specific SecuPress Options

Source: https://context7.com/juliopotier/secupress/llms.txt

Use `secupress_get_module_option()` to read a setting for a specific module, providing a default value and the module slug. `secupress_update_module_option()` writes a single option, and `secupress_update_module_options()` allows for batch updates. `secupress_delete_module_option()` removes all settings for a module.

```php
// Get the brute-force max attempts setting for users-login module
$max_attempts = secupress_get_module_option(
    'login-protection_type_limitloginattempts',
    false,          // default
    'users-login'   // module slug
);

// Enable the "Move Login Page" sub-module option
secupress_update_module_option(
    'move-login_activated',
    1,
    'users-login'
);

// Batch-update several options for a module
secupress_update_module_options(
    [
        'login-protection_type_bannonexistsuser' => 1,
        'login-protection_type_limitloginattempts' => 1,
    ],
    'users-login'
);

// Delete ALL settings for a module (on uninstall / reset)
secupress_delete_module_option( 'firewall' );
```

--------------------------------

### Hook before a block fires

Source: https://context7.com/juliopotier/secupress/llms.txt

Utilize the 'secupress.block' action hook to execute custom code just before a SecuPress block action occurs. This allows for logging or other pre-block operations.

```php
// Hook before a block fires (e.g., to log to an external service)
add_action( 'secupress.block', function( $module, $ip, $args, $block_id ) {
    error_log( "SecuPress blocked $ip via $block_id" );
}, 10, 4 );
```

--------------------------------

### Run a single scanner programmatically

Source: https://context7.com/juliopotier/secupress/llms.txt

Instantiate and run a specific scanner class, such as SecuPress_Scan_Admin_User, to perform a security scan and retrieve its results. The scan() method populates the result with 'good', 'warning', or 'bad' status.

```php
// Run a single scanner programmatically
secupress_require_class( 'scan', 'Admin_User' );
$scanner = SecuPress_Scan_Admin_User::get_instance();
$scanner->scan();  // populates result array with status 'good', 'warning', or 'bad'
$result = $scanner->get_result(); // ['status' => 'bad', 'msgs' => [...]]
```

--------------------------------

### User and Capability Utilities

Source: https://context7.com/juliopotier/secupress/llms.txt

Utilities for user lookup, validation, and capability resolution.

```APIDOC
## `secupress_get_user_by()` / `secupress_is_user()` / `secupress_get_capability()`

Flexible user lookup by any field, validation of WP_User objects, and capability resolution for single/multisite.

### Description
Provides functions to find users by various criteria, validate user objects, and determine required capabilities.

### Usage
```php
// Look up a user by ID, email, login, nicename, or display name
$user = secupress_get_user_by( 42 );            // by ID
$user = secupress_get_user_by( 'jane@example.com' ); // by email

// Validate that something is a real WP_User
$valid = secupress_is_user( $user );         // bool
$user  = secupress_is_user( $user, true );   // returns WP_User or false

// Get the required capability to access SecuPress pages
$cap = secupress_get_capability();

// Check if current site is full HTTPS
$is_https = secupress_site_is_using_https( 'both' );
```
```

--------------------------------

### Activate/Deactivate SecuPress Sub-Modules

Source: https://context7.com/juliopotier/secupress/llms.txt

Use `secupress_activate_submodule()` to enable a sub-module within a parent module, and `secupress_deactivate_submodule()` to disable it. `secupress_activate_submodule_silently()` bypasses admin notices and alert hooks. `secupress_is_submodule_active()` checks the current status. Actions like `secupress.modules.activate_submodule_{submodule_slug}` can be used to hook into activation events.

```php
// Activate "move-login" inside the users-login module
$activated = secupress_activate_submodule( 'users-login', 'move-login' );
// $activated = true if it was inactive before, false if already active

// Activate silently (no admin notice, no alert hook)
secupress_activate_submodule_silently( 'users-login', 'captcha' );

// Deactivate a sub-module
secupress_deactivate_submodule( 'firewall', 'bbq-url-content' );

// Deactivate multiple sub-modules at once
secupress_deactivate_submodule( 'users-login', [ 'move-login', 'captcha' ] );

// Check if a sub-module is currently active
if ( secupress_is_submodule_active( 'users-login', 'move-login' ) ) {
    // sub-module is running
}

// Listen for activation
add_action( 'secupress.modules.activate_submodule_move-login', function( $was_already_active ) {
    if ( ! $was_already_active ) {
        // first-time activation logic
    }
} );
```

--------------------------------

### Options API

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to read or write top-level SecuPress plugin options stored in the `SECUPRESS_SETTINGS_SLUG` site option. Supports pre/post filters for each key.

```APIDOC
## Options API

### `secupress_get_option()` / `secupress_set_option()`

Read or write a top-level SecuPress plugin option stored in the `SECUPRESS_SETTINGS_SLUG` site option. Supports pre/post filters for each key.

```php
// Read the consumer API key (returns false if not set)
$key = secupress_get_option( 'consumer_key' );

// Override via filter (useful for mu-plugins or hosting panels)
add_filter( 'pre_secupress_get_option_consumer_key', function( $pre, $default ) {
    return 'MY-HARDCODED-KEY';
}, 10, 2 );

// Write a single option
secupress_set_option( 'site_is_pro', 1 );

// Bulk-write multiple options at once
$options = get_site_option( SECUPRESS_SETTINGS_SLUG, [] );
$options['consumer_email'] = 'admin@example.com';
$options['consumer_key']   = 'ABCD-1234';
secupress_update_options( $options );
```
```

--------------------------------

### Module Options API

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to read or write options scoped to a specific module. Options are stored in `secupress_{$module}_settings`.

```APIDOC
## Module Options API

### `secupress_get_module_option()` / `secupress_update_module_option()`

Read or write an option scoped to a specific module. Options are stored in `secupress_{$module}_settings`.

```php
// Get the brute-force max attempts setting for users-login module
$max_attempts = secupress_get_module_option(
    'login-protection_type_limitloginattempts',
    false,          // default
    'users-login'   // module slug
);

// Enable the "Move Login Page" sub-module option
secupress_update_module_option(
    'move-login_activated',
    1,
    'users-login'
);

// Batch-update several options for a module
secupress_update_module_options(
    [
        'login-protection_type_bannonexistsuser' => 1,
        'login-protection_type_limitloginattempts' => 1,
    ],
    'users-login'
);

// Delete ALL settings for a module (on uninstall / reset)
secupress_delete_module_option( 'firewall' );
```
```

--------------------------------

### Retrieve all attack data

Source: https://context7.com/juliopotier/secupress/llms.txt

Use secupress_get_attacks('all') to retrieve a comprehensive array of all logged attack data, including per-day counts for specific types and a total count.

```php
// Retrieve all attack data
$all = secupress_get_attacks( 'all' );
/*
[
  'ban_ip'        => ['0116' => 12, '0117' => 3],
  'loginattempts' => ['0116' => 5],
  'all'           => 20,
]
*/
```

--------------------------------

### Pro License Detection

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to detect the presence and status of the SecuPress Pro add-on.

```APIDOC
## `secupress_is_pro()` / `secupress_has_pro()` / `secupress_feature_is_pro()`

Detect whether the Pro add-on is installed and licensed, and check if a specific feature gate is Pro-only.

### Description
Check if SecuPress Pro is installed and licensed, and if specific features are restricted to Pro users.

### Usage
```php
// Is Pro plugin present (regardless of license validity)?
if ( secupress_has_pro() ) {
    echo 'SecuPress Pro plugin is installed.';
}

// Is Pro installed AND licensed?
if ( secupress_is_pro() ) {
    echo 'SecuPress Pro is fully activated.';
}

// Check if a specific settings field is Pro-gated
if ( secupress_feature_is_pro( 'login-protection_sessions_control' ) ) {
    echo 'Session Control requires SecuPress Pro.';
}

// Check Pro license validity directly
if ( secupress_has_pro_license() ) {
    $key = secupress_get_consumer_key();
    $email = secupress_get_consumer_email();
}
```
```

--------------------------------

### IP Handling Functions

Source: https://context7.com/juliopotier/secupress/llms.txt

Retrieve the current visitor's IP address and validate IP strings, supporting wildcard and CIDR formats. Includes an option to override the IP source.

```APIDOC
## IP Handling Functions

### Description
Retrieve the current visitor's IP address and validate IP strings (including wildcard and CIDR range formats).

### Functions
- `secupress_get_ip()`: Retrieves the current visitor's IP address.
- `secupress_ip_is_valid( $ip, $allow_wildcard = false, $flags = null )`: Validates an IP string. Supports wildcards and CIDR notation if `$allow_wildcard` is true. Can also validate specific IP versions using `$flags`.
- `secupress_server_is_ssl()`: Checks if the server is running SSL.

### Filters
- `secupress.ip.get_ip`: Allows overriding the IP source. Example:
```php
add_filter( 'secupress.ip.get_ip', function( $ip ) {
    if ( ! empty( $_SERVER['HTTP_X_REAL_IP'] ) ) {
        return $_SERVER['HTTP_X_REAL_IP'];
    }
    return $ip;
} );
```

### Examples
```php
// Get current visitor IP
$ip = secupress_get_ip();

// Validate a plain IP
$valid = secupress_ip_is_valid( '192.168.1.1' ); // true

// Validate an IPv4 wildcard range
$valid = secupress_ip_is_valid( '192.168.*', true ); // true

// Validate CIDR notation
$valid = secupress_ip_is_valid( '10.0.0.0/24', true ); // true

// Validate only IPv4
$valid = secupress_ip_is_valid( '192.168.1.1', false, FILTER_FLAG_IPV4 ); // true

// Check if the server is running SSL
$is_ssl = secupress_server_is_ssl(); // true / false
```
```

--------------------------------

### Hook before any secupress_die() call

Source: https://context7.com/juliopotier/secupress/llms.txt

Implement custom logic before any request termination by hooking into 'secupress.before.die'. This filter provides details about the message, URL, arguments, and context of the impending termination.

```php
// Hook before ANY secupress_die() call
add_action( 'secupress.before.die', function( $message, $url, $args, $is_scan_request, $context ) {
    // custom pre-die action
}, 10, 5 );
```

--------------------------------

### Extend with a custom scanner

Source: https://context7.com/juliopotier/secupress/llms.txt

Add a custom scanner class to the available tests by filtering the 'secupress.scanner.tests' hook. Ensure your custom class extends SecuPress_Scan and follows the naming convention.

```php
// Extend with a custom scanner via filter
add_filter( 'secupress.scanner.tests', function( $tests ) {
    $tests['firewall'][] = 'My_Custom_Check'; // class: SecuPress_Scan_My_Custom_Check
    return $tests;
} );
```

--------------------------------

### Fetch a single security counter

Source: https://context7.com/juliopotier/secupress/llms.txt

Retrieve a specific security metric, such as the overall 'grade' or 'percent', by passing the desired key as an argument to secupress_get_scanner_counts().

```php
// Fetch a single counter
$grade   = secupress_get_scanner_counts( 'grade' );   // 'A'
$percent = secupress_get_scanner_counts( 'percent' );  // 100
```

--------------------------------

### Module and Sub-module Management

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to retrieve module information and check the activation status of sub-modules.

```APIDOC
## `secupress_get_modules()` / `secupress_is_submodule_active()`

Retrieve the full module registry (titles, icons, sub-module lists) and query the activation status of any sub-module.

### Description
Get the complete module map and check if a specific sub-module is running.

### Usage
```php
// Get the complete module map
$modules = secupress_get_modules();

// Check if a specific sub-module is running
if ( secupress_is_submodule_active( 'sensitive-data', 'blackhole' ) ) {
    echo 'Blackhole trap is active';
}

// Get all currently active sub-modules grouped by parent module
$active = secupress_get_active_submodules();

// Check if a sub-module is Pro-only
$is_pro = secupress_submodule_is_pro( 'users-login', 'double-auth' );

// Generate a SecuPress admin page URL
$url = secupress_admin_url( 'modules', 'users-login' );
```
```

--------------------------------

### .htaccess / Server Rules API

Source: https://context7.com/juliopotier/secupress/llms.txt

Provides functions to write or remove named marker sections in server configuration files like .htaccess and web.config, or display instructions for Nginx.

```APIDOC
## .htaccess / Server Rules API

### Description
Write or remove named marker sections in `.htaccess` (Apache), `web.config` (IIS7), or display manual-edit instructions for Nginx.

### Functions
- `secupress_write_htaccess( $marker, $rules = false )`: Writes or removes rules in `.htaccess` under a unique marker. If `$rules` is empty or false, the section is removed.
- `secupress_add_module_rules_or_notice( $args )`: A high-level helper that automatically handles writing rules for Apache/IIS7 or displaying notices for Nginx. Accepts an array with `marker`, `rules`, `iis_args`, and `title`.
- `secupress_remove_module_rules_or_notice( $marker, $title )`: Removes rules and shows an admin notice if the file is not writable.

### Filters
- `secupress.nginx.notice`: Allows suppressing the Nginx manual-edit notice.

### Example Usage
```php
// Write custom rules to .htaccess under a unique marker
$rules = "RewriteRule ^wp-login-old\.php - [F,L]\n";
$ok = secupress_write_htaccess( 'Block-Old-Login', $rules );
// Creates: # BEGIN SecuPress Block-Old-Login … # END SecuPress

// Remove the rules (pass empty/false)
secupress_write_htaccess( 'Block-Old-Login' );

// High-level module helper (handles Apache / IIS7 / Nginx automatically)
secupress_add_module_rules_or_notice( [
    'marker'   => 'bad-user-agents',
    'rules'    => "RewriteCond %{HTTP_USER_AGENT} ^(curl|wget) [NC]\nRewriteRule .* - [F,L]\n",
    'iis_args' => [],
    'title'    => 'Block Bad User Agents',
] );

// Remove rules and show an admin notice if not writable
secupress_remove_module_rules_or_notice( 'bad-user-agents', 'Block Bad User Agents' );

// Filter Nginx notice display
add_filter( 'secupress.nginx.notice', '__return_false' ); // suppress nginx notice
```
```

--------------------------------

### Retrieve a specific attack type's data

Source: https://context7.com/juliopotier/secupress/llms.txt

Fetch the logged data for a particular attack type, such as 'loginattempts', by passing the attack type string as an argument to secupress_get_attacks().

```php
// Retrieve a specific attack type
$login_attacks = secupress_get_attacks( 'loginattempts' );
```

--------------------------------

### Retrieve fix results

Source: https://context7.com/juliopotier/secupress/llms.txt

Call secupress_get_fix_results() to obtain information about actions taken to fix detected security issues.

```php
// Get fix results
$fixes = secupress_get_fix_results();
```

--------------------------------

### Manually log a custom attack type

Source: https://context7.com/juliopotier/secupress/llms.txt

Record a specific attack type using secupress_log_attack(). This function increments counters for the specified attack and also for the 'all' category.

```php
// Manually log a custom attack type
secupress_log_attack( 'ban_ip' );           // increments ban_ip[MMDD] and all
secupress_log_attack( 'loginattempts' );
```

--------------------------------

### Block request with custom message

Source: https://context7.com/juliopotier/secupress/llms.txt

Use secupress_block() to terminate a request and display a custom message to the user. You can also specify a custom HTTP status code.

```php
// Block with a custom message
secupress_block( 'move-login',
    [
        'code'    => 404,
        'content' => 'This page does not exist.',
    ]
);
```

--------------------------------

### Sub-Module Activation API

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to activate or deactivate a named sub-module within a parent module, firing the appropriate hooks and writing activation notices.

```APIDOC
## Sub-Module Activation API

### `secupress_activate_submodule()` / `secupress_deactivate_submodule()`

Activate or deactivate a named sub-module within a parent module, firing the appropriate hooks and writing activation notices.

```php
// Activate "move-login" inside the users-login module
$activated = secupress_activate_submodule( 'users-login', 'move-login' );
// $activated = true if it was inactive before, false if already active

// Activate silently (no admin notice, no alert hook)
secupress_activate_submodule_silently( 'users-login', 'captcha' );

// Deactivate a sub-module
secupress_deactivate_submodule( 'firewall', 'bbq-url-content' );

// Deactivate multiple sub-modules at once
secupress_deactivate_submodule( 'users-login', [ 'move-login', 'captcha' ] );

// Check if a sub-module is currently active
if ( secupress_is_submodule_active( 'users-login', 'move-login' ) ) {
    // sub-module is running
}

// Listen for activation
add_action( 'secupress.modules.activate_submodule_move-login', function( $was_already_active ) {
    if ( ! $was_already_active ) {
        // first-time activation logic
    }
} );
```
```

--------------------------------

### Block request with custom HTTP code

Source: https://context7.com/juliopotier/secupress/llms.txt

Block a request using secupress_block() and specify a custom HTTP status code, such as 403, by passing it in the arguments array.

```php
// Block with custom HTTP code
secupress_block( 'xmlrpc', [ 'code' => 403 ] );
```

--------------------------------

### Retrieve all stored scan results

Source: https://context7.com/juliopotier/secupress/llms.txt

Use secupress_get_scan_results() to fetch all previously saved scan results for different security tests. This function returns an array where keys are scanner names and values contain their status and messages.

```php
// Get all previously stored scan results
$results = secupress_get_scan_results();
// ['admin_user' => ['status' => 'good'], 'easy_login' => ['status' => 'bad', 'msgs' => [...]], ...]
```

--------------------------------

### Scanner Management

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to retrieve scanner information, run individual scanners, and manage scanner results.

```APIDOC
## `secupress_get_scanners()`

### Description
Retrieves a map of all security test identifiers, grouped by module. Each identifier corresponds to a `SecuPress_Scan_{Name}` class.

### Usage
```php
$tests = secupress_get_scanners();
```

## `SecuPress_Scan` Class Methods

### Description
Provides methods to scan and fix security issues for a specific test.

### Methods
- `scan()`: Executes the security scan and populates the result.
- `fix()`: Attempts to fix the detected security issue.
- `get_result()`: Returns the result of the scan, including status and messages.

### Usage
```php
secupress_require_class( 'scan', 'Admin_User' );
$scanner = SecuPress_Scan_Admin_User::get_instance();
$scanner->scan();
$result = $scanner->get_result();
$scanner->fix();
```

## `secupress_get_scanner_counts()` / `secupress_get_scan_results()`

### Description
Retrieves aggregated scan results, counts by status, and the computed security letter grade.

### Usage
```php
$results = secupress_get_scan_results();
$counts = secupress_get_scanner_counts();
$grade = secupress_get_scanner_counts( 'grade' );
```
```

--------------------------------

### Block request with default 403 status

Source: https://context7.com/juliopotier/secupress/llms.txt

Terminate a request and display a SecuPress block page using secupress_block(). The default behavior logs the attack as 'ban_ip' and uses a 403 HTTP status code.

```php
// Block with default 403 and log as 'ban_ip'
secupress_block( 'bbq-url-content' );
```

--------------------------------

### Attack Logging API

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to record and retrieve statistics about blocked attacks.

```APIDOC
## `secupress_log_attack()` / `secupress_get_attacks()`

### Description
Records blocked attacks by type, maintaining per-day counters, and allows retrieval of attack statistics.

### Parameters
- `type` (string): The type of attack to log (e.g., 'ban_ip', 'loginattempts').
- `get_type` (string, optional): The type of attack data to retrieve. Use 'all' to get all data.

### Usage
```php
// Manually log a custom attack type
secupress_log_attack( 'ban_ip' );

// Retrieve all attack data
$all = secupress_get_attacks( 'all' );

// Retrieve a specific attack type
$login_attacks = secupress_get_attacks( 'loginattempts' );
```

## `secupress_attacks_get_type_title()`

### Description
Retrieves the human-readable title for a given attack type.

### Parameters
- `type` (string): The internal attack type identifier.

### Usage
```php
$title = secupress_attacks_get_type_title( 'loginattempts' ); // Returns "Login Attempts"
```
```

--------------------------------

### Blocking API

Source: https://context7.com/juliopotier/secupress/llms.txt

Functions to block requests and display formatted SecuPress block pages.

```APIDOC
## `secupress_block()` / `secupress_die()`

### Description
Terminates a request with a formatted SecuPress block page, logs the attack type, and fires hooks before execution stops.

### Parameters
- `module` (string): The type of attack or module being blocked (e.g., 'bbq-url-content', 'xmlrpc').
- `args` (array, optional): An array of arguments to customize the block behavior, such as:
  - `code` (int): The HTTP response code to send (default is 403).
  - `content` (string): A custom message to display on the block page.

### Usage
```php
// Block with default 403 and log as 'ban_ip'
secupress_block( 'bbq-url-content' );

// Block with custom HTTP code
secupress_block( 'xmlrpc', [ 'code' => 403 ] );

// Block with a custom message
secupress_block( 'move-login', [
    'code'    => 404,
    'content' => 'This page does not exist.',
] );
```

### Hooks
- `secupress.block`: Fires before a block occurs.
- `secupress.before.die`: Fires before any `secupress_die()` call.
- `secupress.die.message`: Filters the message shown to blocked users.
```

--------------------------------

### Email & Notifications API

Source: https://context7.com/juliopotier/secupress/llms.txt

Provides a function to send SecuPress-branded emails with automatic placeholder replacement and filterable headers.

```APIDOC
## Email & Notifications API

### Description
Send a SecuPress-branded email with automatic placeholder replacement and filterable headers.

### Function
- `secupress_send_mail( $to, $subject, $message, $headers = [], $attachments = [] )`: Sends an email.
  - `$to`: The recipient's email address.
  - `$subject`: The email subject. Supports placeholders like `###SITENAME###`.
  - `$message`: The email message body. Supports placeholders like `###SITEURL###` and `###LOGINURL###`.
  - `$headers`: An array of extra email headers.
  - `$attachments`: An array of attachments.

### Filters
- `secupress.mail.replacement`: Allows adding custom placeholders to be replaced.
- `secupress.mail.replaced`: Allows defining the values for custom placeholders.
- `secupress.get_email`: Allows overriding the default 'From' email address.
- `secupress.mail.before.wp_mail`: Hook that runs before `wp_mail()` is called, allowing modification of the arguments.

### Example Usage
```php
// Send a security alert email
secupress_send_mail(
    'admin@example.com',                          // recipient
    '[###SITENAME###] Security Alert',            // subject (###SITENAME### is replaced)
    "Hello,\n\nAn intrusion attempt was detected on ###SITEURL###.\n\nLogin: ###LOGINURL###",
    [],    // extra headers
    []     // attachments
);

// Add a custom placeholder replacement
add_filter( 'secupress.mail.replacement', function( $tags ) {
    $tags[] = '###ADMIN_NAME###';
    return $tags;
} );
add_filter( 'secupress.mail.replaced', function( $values ) {
    $user = get_user_by( 'email', get_option( 'admin_email' ) );
    $values[] = $user ? $user->display_name : 'Administrator';
    return $values;
} );

// Override the From address
add_filter( 'secupress.get_email', function( $email ) {
    return 'security@example.com';
} );

// Hook before the mail is sent
add_action( 'secupress.mail.before.wp_mail', function( $args ) {
    // [$to, $subject, $message, $headers, $attachments]
    error_log( 'SecuPress sending mail to ' . $args[0] );
} );
```
```

--------------------------------

### Send SecuPress Branded Emails

Source: https://context7.com/juliopotier/secupress/llms.txt

Send emails with SecuPress branding, supporting automatic placeholder replacement and filterable headers. Custom placeholders and 'From' addresses can be managed via filters.

```php
// Send a security alert email with built-in placeholders
secupress_send_mail(
    'admin@example.com',                          // recipient
    '[###SITENAME###] Security Alert',            // subject (###SITENAME### is replaced)
    "Hello,\n\nAn intrusion attempt was detected on ###SITEURL###.\n\nLogin: ###LOGINURL###",
    [],    // extra headers
    []     // attachments
);
```

```php
// Add a custom placeholder replacement
add_filter( 'secupress.mail.replacement', function( $tags ) {
    $tags[] = '###ADMIN_NAME###';
    return $tags;
} );
add_filter( 'secupress.mail.replaced', function( $values ) {
    $user = get_user_by( 'email', get_option( 'admin_email' ) );
    $values[] = $user ? $user->display_name : 'Administrator';
    return $values;
} );
```

```php
// Override the From address
add_filter( 'secupress.get_email', function( $email ) {
    return 'security@example.com';
} );
```

```php
// Hook before the mail is sent
add_action( 'secupress.mail.before.wp_mail', function( $args ) {
    // [$to, $subject, $message, $headers, $attachments]
    error_log( 'SecuPress sending mail to ' . $args[0] );
} );
```

--------------------------------

### Malware Scanner API

Source: https://context7.com/juliopotier/secupress/llms.txt

Provides functions to retrieve available malware scan engines and the last scan time.

```APIDOC
## Malware Scanner API

### Description
Returns an ordered list of available malware scan engines with metadata used to render the scanner UI, and retrieves the timestamp of the last malware scan.

### Functions
- `secupress_get_malware_scanners()`: Returns an array of available malware scanners, each with metadata like icon, file, callback function, and name.
- `secupress_get_malware_scan_last_time()`: Returns the Unix timestamp of the last malware scan, or 0 if no scan has been performed.

### Example Response Structure for `secupress_get_malware_scanners()`
```json
[
  {'icon': 'radar',     'file': 'malware_keywords',  'name': 'Malware Scanner', ...},
  {'icon': 'data-base', 'file': 'malware_keywords_db','cback': 'secupress_get_database_scanner', 'name': 'Database Scanner', ...},
  {'icon': 'cog',       'file': 'tag_attr',           'cback': 'secupress_get_content_spam_scanner', 'name': 'SEO Poisoning Scanner', ...},
  {'icon': 'core',                                       'cback': 'secupress_file_scanner_get_full_filetree', 'name': 'WordPress Core Files Integrity', ...}
]
```

### Example Usage
```php
// Get available malware scanners
$scanners = secupress_get_malware_scanners();

// Check when the last malware scan ran
$last_scan = secupress_get_malware_scan_last_time(); // Unix timestamp or 0
if ( $last_scan > 0 ) {
    echo 'Last scan: ' . date( 'Y-m-d H:i', $last_scan );
}
```
```

--------------------------------

### Fix detected security issues

Source: https://context7.com/juliopotier/secupress/llms.txt

After a scanner has identified issues, call the fix() method on the scanner instance to attempt to resolve them.

```php
// Fix the detected issue
$scanner->fix();
```

--------------------------------

### Modify the message shown to blocked users

Source: https://context7.com/juliopotier/secupress/llms.txt

Customize the message displayed to users when a request is blocked by hooking into the 'secupress.die.message' filter. This allows you to append or modify the default block message.

```php
// Modify the message shown to blocked users
add_filter( 'secupress.die.message', function( $message, $url, $args, $is_scan_request, $context ) {
    return $message . '<p>Contact admin@example.com for assistance.</p>';
}, 10, 5 );
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.