Gated shell access

A gated shell access is a security feature that

  • controls direct, interactive root shell access for supported shell commands,

  • requires authorization using a Cisco or customer Consent Token (CT) path before restricting access, and

  • stores in HWTAM Secure Object storage.

Consent Token authorization applies to the shell-access restriction operation. This feature uses a separate Consent Token challenge-response workflow for each shell session.

Table 1. Feature History Table

Feature Name

Release Information

Feature Description

Gated shell access

Release 26.3.1

Shell access restrictions require Consent Token authorization for direct root shell access initiated through supported shell commands.

Key features of gated shell access

Use this reference to determine whether a platform supports gated shell access and to identify the associated restrictions and CLI commands.

Key features:

  • Gates only direct shell access via supported CLI commands (such as bash , run , and attach ). Indirect access through scripts or internal processes is not gated in the initial release.

  • It enables restriction or unrestriction of gated shell access, ensuring that only authorized personnel can change shell-access policies.

  • Depends on the consent token infrastructure to be present and supported on the platform for operation.

  • The restricted-shell selection is stored in an HWTAM secure object.

Table 2. Gated shell access CLI commands

Command

Purpose

platform security shell-access restrict challenge {cisco | owner}

Initiates the Consent Token challenge for the selected Cisco or customer authorization path.

platform security shell-access restrict response <response_string>

Submits the Consent Token response to authorize and complete the shell-access restriction operation.

platform security shell-access restrict terminate-auth

Terminates the pending Consent Token authorization request for shell-access restriction.

platform security shell-access unrestrict challenge {cisco | owner}

Starts the Consent Token authorization flow to remove the restriction.

platform security shell-access unrestrict response <response_string>

Submits the Consent Token response for unrestriction.

platform security shell-access unrestrict terminate-auth

Terminates the pending unrestriction authorization request operation.

show platform security shell-access status

Displays the restricted-shell configuration and handshake status.

The HWTAM Secure Object holds the restricted-shell selection and handshake state. The restricted-shell selection is preserved across reboots and reloads.

How gated shell access works

The process occurs when a user restricts direct interactive shell access on a platform that supports the Consent Token infrastructure.

Summary

When a user restricts shell access, the system records the restriction state in the HWTAM Secure Object. Subsequent supported direct, interactive root shell access attempts check this state and are denied while the restriction is active.

Workflow

These stages describe the gated shell access workflow:

  1. A user restricts shell access or requests access to a direct, interactive root shell.
  2. The system stores the restricted-shell access state in the HWTAM Secure Object and applies the restriction to supported direct, interactive root shell access.
  3. The user must complete the consent token response challenge handshake.
  4. The user enters the Consent Token response. When the response succeeds, the system permits one root shell instance for that user session.
  5. A user starts the unrestriction authorization flow, submits the response, and the system returns to the default non-gated root shell behavior after successful authorization.

Restrict shell access using a Cisco-signed Consent Token

Use this task to restrict supported direct, interactive root shell access by using a Cisco-signed Consent Token.

Procedure

Step 1

Generate the challenge string on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access restrict challenge cisco
Thu Aug 20 06:06:33.888 UTC

+--------------------------------------+
Node location: node0_RP0_CPU0
+--------------------------------------+
Challenge string:
<challenge_string>

This produces a challenge string containing the device ID, a nonce, and the requested action.

Step 2

Submit the challenge string to a Cisco TAC engineer. Cisco verifies that the requester is the legitimate device owner and is authorized to perform the requested action. If verified, the TAC engineer provides a signed response string.

Step 3

Paste the response string provided by the TAC engineer when prompted, to install the signed response on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access restrict response
Thu Aug 20 06:07:07.090 UTC
***************************************************************
Please enter challenge response string for node location node0_RP0_CPU0
***************************************************************
<response_string>
Successfully accepted challenge-response for Restrict Shell Access in node0_RP0_CPU0

Example:

The router validates the signature and confirms that the device ID and nonce match its own records. If valid, this restricts the direct shell access.

Note

 

Unrestrict shell access using a Cisco-signed Consent Token

Use this task to unrestrict the supported direct, interactive root shell access by using a Cisco-signed Consent Token.

Before you begin

Ensure that gated shell access is restricted. For more information about restricting shell access by using a Cisco-signed Consent Token, see Restrict shell access using a Cisco-signed Consent Token.

Procedure

Step 1

Generate an unrestrict challenge on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access unrestrict challenge
Thu Aug 20 06:06:33.888 UTC

+--------------------------------------+
Node location: node0_RP0_CPU0
+--------------------------------------+
Challenge string:
<challenge_string>

Step 2

Submit the challenge string to a Cisco TAC engineer. Cisco verifies that the requester is the legitimate device owner and is authorized to perform the requested action. If verified, the TAC engineer provides a signed response string.

Step 3

Paste the response string provided by the TAC engineer when prompted, to install the signed response on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access unrestrict response
Thu Aug 20 06:07:07.090 UTC
***************************************************************
Please enter challenge response string for node location node0_RP0_CPU0
***************************************************************
<response_string>
Successfully accepted challenge-response for Unrestrict Shell Access in node0_RP0_CPU0

The router validates the signature and confirms that the device ID and nonce match its own records. If valid, the response removes the restriction on direct shell access.

Note

 

If required, to terminate a pending Consent Token handshake for shell-access restriction, see Terminate a pending Consent Token authorization request.

Step 4

Verify the shell-access status.

Example:

RP/0/RP0/CPU0:ios# show platform security shell-access status
Thu Aug 20 05:20:01.690 UTC
Restricted shell access enabled: No

Restrict shell access using an owner Consent Token

Use this task to restrict supported direct, interactive root shell access by using an owner Consent Token.

Procedure

Step 1

Generate the challenge string on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access restrict challenge owner
Thu Aug 20 06:06:33.888 UTC

+--------------------------------------+
Node location: node0_RP0_CPU0
+--------------------------------------+
Challenge string:
<challenge_string>

This produces a challenge string containing the device ID, a nonce, and the requested action.

Step 2

To generate the response string owner key type , refer to Provisioning customer consent tokens.

Step 3

Paste the response string provided by the TAC engineer when prompted, to install the signed response on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access restrict response
Thu Aug 20 06:07:07.090 UTC
***************************************************************
Please enter challenge response string for node location node0_RP0_CPU0
***************************************************************
<response_string>
Successfully accepted challenge-response for Restrict Shell Access in node0_RP0_CPU0

The router validates the signature and confirms that the device ID and nonce match its own records. If valid, this restricts the direct shell access.

Note

 

Unrestrict shell access using an owner Consent Token

Restore unrestricted root shell access by removing the restricted-shell setting, allowing access to advanced system features when necessary.

Use this task to unrestrict the supported direct, interactive root shell access by using an owner Consent Token.

Before you begin

Ensure that gated shell access is restricted. For more information about restricting shell access by using an owner Consent Token, see Restrict shell access using an owner Consent Token.

Procedure

Step 1

Generate an unrestrict challenge on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access unrestrict challenge
Thu Aug 20 06:06:33.888 UTC
+--------------------------------------+
Node location: node0_RP0_CPU0
+--------------------------------------+
Challenge string:
<challenge_string>

Step 2

To generate the response string owner key type, refer to Provisioning customer consent tokens.

Step 3

Paste the response string provided by the TAC engineer when prompted, to install the signed response on the router.

Example:

RP/0/RP0/CPU0:ios# platform security shell-access unrestrict response
Thu Aug 20 06:07:07.090 UTC
***************************************************************
Please enter challenge response string for node location node0_RP0_CPU0
***************************************************************
<response_string>
Successfully accepted challenge-response for Unrestrict Shell Access in node0_RP0_CPU0

The router validates the signature and confirms that the device ID and nonce match its own records. If valid, the response removes the restriction on direct shell access.

Note

 

If required, to terminate a pending Consent Token handshake for shell-access restriction, see Terminate a pending Consent Token authorization request.

Step 4

Verify the shell-access status.

Example:

RP/0/RP0/CPU0:ios# show platform security shell-access status
Thu Aug 20 05:20:01.690 UTC
Restricted shell access enabled: No

Terminate a pending Consent Token authorization request

Use this task to terminate a pending Consent Token authorization request for restrict or unrestrict shell access.

Use this task only after generating a Consent Token challenge and before submitting a response. The terminate command applies to both Cisco and owner Consent Token requests.

Procedure

Step 1

Generate a Consent Token challenge for either restrict or unrestrict shell access, as described in the applicable task.

Do not submit the response.

Step 2

To terminate a pending Consent Token handshake:

  • For restrict shell access, use platform security shell-access restrict terminate-auth command. 

    RP/0/RP0/CPU0:ios#
RP/0/RP0/CPU0:ios# platform security shell-access restrict challenge cisco
Thu Aug 20 06:08:45.228 UTC

+--------------------------------------+
Node location: node0_RP0_CPU0
+--------------------------------------+
Challenge string:
<challenge_string>
RP/0/RP0/CPU0:ios# platform security shell-access restrict terminate-auth
Thu Aug 20 06:09:10.334 UTC
Successfully terminated challenge session for Restrict Shell Access in node0_RP0_CPU0

  • For unrestrict shell access, use platform security shell-access unrestrict terminate-auth command. 

    RP/0/RP0/CPU0:ios#
RP/0/RP0/CPU0:ios# platform security shell-access unrestrict challenge cisco
Thu Aug 20 06:08:45.228 UTC

+--------------------------------------+
Node location: node0_RP0_CPU0
+--------------------------------------+
Challenge string:
<challenge_string>
RP/0/RP0/CPU0:ios# platform security shell-access unrestrict terminate-auth
Thu Aug 20 06:09:10.334 UTC
Successfully terminated challenge session for Unrestrict Shell Access in node0_RP0_CPU0

The system confirms that it terminated the pending authorization request.

Access a restricted shell

Use this task to access a restricted, direct, interactive root shell by completing the Consent Token challenge-response workflow.

This task applies to supported direct, interactive root shell commands, such as bash, run or attach.

Procedure

Step 1

Restrict shell access by using either a Cisco-signed Consent Token or an Owner Consent Token.

Step 2

Enter the bash, run or attach command. When prompted, complete the cisco or owner Consent Token challenge-response.

A valid response permits the requested shell instance.

Example:

RP/0/RP0/CPU0:ios# bash
Thu Aug 20 06:01:15.407 UTC
Restricted shell access is enabled. Please obtain a consent token to proceed.
Consent token challenge: <challenge_string>
Enter challenge response, or Ctrl-C to terminate:
<response_string>
Challenge response accepted successfully.