Guide to API Privilege Escalation

Introduction

Warning:

Poor implementations of this system may cause root-privilege vulnerabilities and compromised servers.

To run a function with escalated privileges, call a function through the Call method or use the send_cpwrapd_request pluggable wrapper. The system manages privilege escalation, and ensures that the user can only run the permitted code.

Notes:

  • This set of documents applies to cPanel & WHM version 11.38 and later.
  • cPanel, Inc. introduced the Call method for Perl admin modules in cPanel & WHM version 54 in order to simplify construction of modules. We recommend that you write admin modules with this method when possible. For earlier versions and other programming languages, use the Standard Method.

The Call Method (54+) 

Note:

cPanel, Inc. introduced this functionality in cPanel & WHM version 54 for admin modules in Perl.

Basic Usage

As of cPanel & WHM version 54, cPanel recommends that you develop admin modules as subclasses of the cPanel-providedCpanel::AdminBin::Script::Call base class. This class, and the Cpanel::AdminBin::Call module that accompanies it, contain privilege escalation logic so that admin modules are simpler to write and call.

To make a module “TheModule” in the namespace “TheNameSpace” perform the following steps:

  1. Create the /usr/local/cpanel/bin/admin/TheNameSpace directory.
  2. Run the following command to create the configuration file:

    echo mode=full > /usr/local/cpanel/bin/admin/TheNamespace/TheModule.conf
  3. Create your new module in the /usr/local/cpanel/bin/admin/TheNamespace/TheModule file.

  4. Set that file to be executable with the following command: chmod 0700 /usr/local/cpanel/bin/admin/TheNamespace/TheModule

Example

The following example admin module uses the Call method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/usr/local/cpanel/3rdparty/bin/perl
 
package TheNamespace::TheModule;
 
use strict;
 
use parent 'Cpanel::AdminBin::Script::Call';
 
__PACKAGE__->run() if !caller;
 
sub _actions { return qw( DO_GOOD ) }
 
sub DO_GOOD {
 my ($self, $arg1, $arg2) = @_;
 return "I did good with “$arg1” and “$arg2->[0]”.";
}
 
1;

Class methods:

run(OPTS) runs the script after it checks whether the first element in the value of the @ARGV array is --bincheck. If --bincheck exists in the@ARGV array, the system prints the BinCheck ok message with a trailing newline and the process performs an exit().

This is normally how Call-type admin modules should invoke themselves when run from a script.

OPTS is an optional list of arguments that can include:

  • alarm — An integer that represents a timeout value for the script. This option defaults to 350 seconds.

For example:

__PACKAGE__->run( alarm => 600 ); #allow 10 minutes rather than the default 350 seconds

new(OPTS) is identical to run(), but it does not check if the first element in the value of the @ARGV array is --bincheck. This will help you test your module.

For example:

TheTestedModule->new();

DO_GOOD

To call the DO_GOOD function from unprivileged code, you would use the following:

my $resp = Cpanel::AdminBin::Call::call('TheNamespace''TheModule''DO_GOOD''first arg', ['second arg']);

The above example passes two parameters, 'first arg' and ['second arg'], to the DO_GOOD method in the admin module. This particular example returns one value, but you may also return a list. Input parameters and return values may be scalars, array references, or hash references. This structure does not support scalar references, references that use the bless() function, and self-referential data structures as inputs or outputs.

The code calls the admin function with the same context (void, scalar, or list) as the  Cpanel::AdminBin::Call::call() method itself. (The system handles “mismatched” returns — for example, returning an array in scalar context — as Perl handles them.) The admin module traps exceptions, and then re-throws them without a stack trace in the code that calls them.

Note:

The $self parameter in the example contains a reference to the instance of your admin module and class. Your class will inherit several useful methods such as get_caller_username() from the Cpanel::AdminBin::Script::Call module.

The Standard Method 

Basic Usage

To use privilege escalation in your custom code, perform the following steps:

  1. Create the following files:
    • A configuration file.
    • An application file.

    Notes:

    • Download a simple example file: Simple.tar.gz.
    • Download an advanced example file: Advanced.tar.gz.
    • Never use this any of these example files on a production system.
  2. Store these files in a new namespace in the  /usr/local/cpanel/bin/admin/  directory. 
    • The namespace and the directory name must be identical.
    • Do not create your AdminBin application inside the Cpanel namespace.
  3. Use the Cpanel::AdminBin::send_cpwrapd_request method to call the application as the authenticated user.

Security requirements

Whenever you use this system, do not manipulate files or directories that a user owns as the root user, or execute any actions on unvalidated input.

Warning:

You must adhere to the following security practices:

  • Only use this system to execute code that must run as the root user.
  • Thoroughly validate any input that passes through this system.
  • Sanitize the admin script's environment.

 

To sanitize the admin script's environment, set environment variables to limit the paths from which the script loads libraries. 

  • This action sanitizes the @INC array, and ensures that users cannot load arbitrary libraries.
  • The following example adds the /usr/local/cpanel/ directory to the environment, and then removes entries that do not match standard Perl library paths:

    1
    2
    3
    4
    BEGIN {
        unshift @INC'/usr/local/cpanel';
        @INC grep( !/(^\.|\.\.|\/\.+)/, @INC );
    }

The Standard Method 

Basic Usage

To use privilege escalation in your custom code, perform the following steps:

  1. Create the following files:
    • A configuration file.
    • An application file.

    Notes:

    • Download a simple example file: Simple.tar.gz.
    • Download an advanced example file: Advanced.tar.gz.
    • Never use this any of these example files on a production system.
  2. Store these files in a new namespace in the  /usr/local/cpanel/bin/admin/  directory. 
    • The namespace and the directory name must be identical.
    • Do not create your AdminBin application inside the Cpanel namespace.
  3. Use the Cpanel::AdminBin::send_cpwrapd_request method to call the application as the authenticated user.

Security requirements

 

Whenever you use this system, do not manipulate files or directories that a user owns as the root user, or execute any actions on unvalidated input.

Warning:

You must adhere to the following security practices:

  • Only use this system to execute code that must run as the root user.
  • Thoroughly validate any input that passes through this system.
  • Sanitize the admin script's environment.

 

To sanitize the admin script's environment, set environment variables to limit the paths from which the script loads libraries. 

  • This action sanitizes the @INC array, and ensures that users cannot load arbitrary libraries.
  • The following example adds the /usr/local/cpanel/ directory to the environment, and then removes entries that do not match standard Perl library paths:

    1
    2
    3
    4
    BEGIN {
        unshift @INC'/usr/local/cpanel';
        @INC grep( !/(^\.|\.\.|\/\.+)/, @INC );
    }

  • 0 Users Found This Useful
Was this answer helpful?

Related Articles

The cPanel Interface

For  cPanel  &  WHM  version  58 Overview The cPanel interface is...

User Preferences

For cPanel & WHM version 58 Overview This document outlines how to access your cPanel...

Manage External Authentications

For cPanel & WHM version 58 Overview Manage credentials Additional documentation...

What is cPanelID?

In This Article:  Overview ServicesHow to get a cPanelID cPanelID External...

Guide to cPanel Interface Customization - cPanel Style Development

Introduction You can develop custom styles that modify the appearance of the cPanel interface....