| 1 |
.TH CAPSH 1 "2025-03-19" "libcap" "User Commands" |
| 2 |
.SH NAME |
| 3 |
capsh \- capability shell wrapper |
| 4 |
.SH SYNOPSIS |
| 5 |
.B capsh |
| 6 |
[\fIOPTION\fR]... |
| 7 |
.SH DESCRIPTION |
| 8 |
Linux capability support and use can be explored and constrained with |
| 9 |
this tool. This tool provides a handy wrapper for certain types |
| 10 |
of capability testing and environment creation. It also provides some |
| 11 |
debugging features useful for summarizing capability state. |
| 12 |
.SH OPTIONS |
| 13 |
.B capsh |
| 14 |
takes a number of optional arguments, acting on them in the |
| 15 |
order they are provided. They are as follows: |
| 16 |
.TP |
| 17 |
.B \-\-help |
| 18 |
Display the list of commands supported by |
| 19 |
.BR capsh . |
| 20 |
.TP |
| 21 |
.B \-\-print |
| 22 |
Display prevailing capability and related state. |
| 23 |
.TP |
| 24 |
.B \-\-current |
| 25 |
Display prevailing capability state, 1e capabilities and IAB vector. |
| 26 |
.TP |
| 27 |
.BI \-\- " [args]" |
| 28 |
Execute |
| 29 |
.B /bin/bash |
| 30 |
with trailing arguments. Note, you can use |
| 31 |
.B \-c 'command to execute' |
| 32 |
for specific commands. |
| 33 |
.TP |
| 34 |
.BI \-\+ " [args]" |
| 35 |
Uses \fBcap_launch\fP(3) to fork a child to execute the shell. When |
| 36 |
the child exits, \fBcapsh\fP exits with the status of the child or 1 |
| 37 |
in the case that the child was terminated by a signal. |
| 38 |
.TP |
| 39 |
.BI == " [args]" |
| 40 |
Execute |
| 41 |
.B capsh |
| 42 |
again with the remaining arguments. Useful for testing |
| 43 |
.BR exec () |
| 44 |
behavior. Note, PATH is searched when the running |
| 45 |
.B capsh |
| 46 |
was found via the shell's PATH searching. If the |
| 47 |
.B exec |
| 48 |
occurs after a |
| 49 |
.BI \-\-chroot= /some/path |
| 50 |
argument the PATH located binary may not be resolve to the same binary |
| 51 |
as that running initially. This behavior is an intended feature as it |
| 52 |
can complete the chroot transition. |
| 53 |
.TP |
| 54 |
.BI =\+ " [args]" |
| 55 |
Uses \fBcap_launch\fP(3) to fork a child to re-execute |
| 56 |
\fBcapsh\fP. When this child exits, \fBcapsh\fP exits with the status |
| 57 |
of the child or 1 in the case that the child was terminated by a |
| 58 |
signal. |
| 59 |
.TP |
| 60 |
.BI \-\-caps= cap-set |
| 61 |
Set the prevailing process capabilities to those specified by |
| 62 |
.IR cap-set . |
| 63 |
Where |
| 64 |
.I cap-set |
| 65 |
is a text-representation of a capability `Set' as per |
| 66 |
.BR cap_text_formats (7). |
| 67 |
.TP |
| 68 |
.BI \-\-drop= cap-list |
| 69 |
Remove the listed capabilities from the prevailing bounding set. The |
| 70 |
capabilities are a comma-separated list of capabilities as recognized |
| 71 |
by the |
| 72 |
.BR cap_from_name (3) |
| 73 |
function. Use of this feature requires that |
| 74 |
.B capsh |
| 75 |
is operating with |
| 76 |
.B CAP_SETPCAP |
| 77 |
in its effective set. |
| 78 |
.TP |
| 79 |
.BI \-\-inh= cap-list |
| 80 |
Set the inheritable set of capabilities for the current process to |
| 81 |
equal those provided in the comma separated list. For this action to |
| 82 |
succeed, the prevailing process should already have each of these |
| 83 |
capabilities in the union of the current inheritable and permitted |
| 84 |
capability sets, or |
| 85 |
.B capsh |
| 86 |
should be operating with |
| 87 |
.B CAP_SETPCAP |
| 88 |
in its effective set. |
| 89 |
.TP |
| 90 |
.BI \-\-user= username |
| 91 |
Assume the identity of the named user. That is, look up the user's |
| 92 |
UID and GID |
| 93 |
with |
| 94 |
.BR getpwuid (3) |
| 95 |
and their group memberships with |
| 96 |
.BR getgrouplist (3) |
| 97 |
and set them all using |
| 98 |
.BR cap_setuid (3) |
| 99 |
and |
| 100 |
.BR cap_setgroups (3). |
| 101 |
Following this command, the effective capabilities will be cleared, |
| 102 |
but the permitted set will not be, so the running program is still |
| 103 |
privileged. |
| 104 |
.TP |
| 105 |
.B \-\-mode |
| 106 |
Display the prevailing libcap mode as guessed by the |
| 107 |
.BR cap_get_mode (3) |
| 108 |
function. |
| 109 |
.TP |
| 110 |
.BR \-\-mode= <mode> |
| 111 |
Force the program into a |
| 112 |
.BR cap_set_mode (3) |
| 113 |
security mode. This is a set of securebits and prevailing capability |
| 114 |
arrangement recommended for its pre-determined security stance. |
| 115 |
.TP |
| 116 |
.B \-\-modes |
| 117 |
Lists all of the libcap modes supported by |
| 118 |
.BR \-\-mode= <mode>. |
| 119 |
.TP |
| 120 |
.BR \-\-inmode= <mode> |
| 121 |
Confirm that the prevailing mode is that specified in |
| 122 |
.IR <mode> , |
| 123 |
or exit with a status 1. |
| 124 |
.TP |
| 125 |
.BI \-\-uid= id |
| 126 |
Force all |
| 127 |
UID |
| 128 |
values to equal |
| 129 |
.I id |
| 130 |
using the |
| 131 |
.BR setuid (2) |
| 132 |
system call. This argument may require explicit preparation of the |
| 133 |
effective set. |
| 134 |
.TP |
| 135 |
.BR \-\-cap\-uid= <uid> |
| 136 |
use the |
| 137 |
.BR cap_setuid (3) |
| 138 |
function to set the UID of the current process. This performs all |
| 139 |
preparations for setting the UID without dropping capabilities in the |
| 140 |
process. Following this command the prevailing effective capabilities |
| 141 |
will be lowered. |
| 142 |
.TP |
| 143 |
.BI \-\-is\-uid= <id> |
| 144 |
Exit with status 1 unless the current |
| 145 |
UID equals |
| 146 |
.IR <id> . |
| 147 |
.TP |
| 148 |
.BI \-\-gid= <id> |
| 149 |
Force all |
| 150 |
GID |
| 151 |
values to equal |
| 152 |
.I id |
| 153 |
using the |
| 154 |
.BR setgid (2) |
| 155 |
system call. |
| 156 |
.TP |
| 157 |
.BI \-\-is\-gid= <id> |
| 158 |
Exit with status 1 unless the current |
| 159 |
GIQ equals |
| 160 |
.IR <id> . |
| 161 |
.TP |
| 162 |
.BI \-\-groups= <gid-list> |
| 163 |
Set the supplementary groups to the numerical list provided. The |
| 164 |
groups are set with the |
| 165 |
.BR setgroups (2) |
| 166 |
system call. See |
| 167 |
.B \-\-user |
| 168 |
for a more convenient way of doing this. |
| 169 |
.TP |
| 170 |
.BI \-\-keep= <0|1> |
| 171 |
In a non-pure capability mode, the kernel provides liberal privilege |
| 172 |
to the super-user. However, it is normally the case that when the |
| 173 |
super-user changes |
| 174 |
UID |
| 175 |
to some lesser user, then capabilities are dropped. For these |
| 176 |
situations, the kernel can permit the process to retain its |
| 177 |
capabilities after a |
| 178 |
.BR setuid (2) |
| 179 |
system call. This feature is known as |
| 180 |
.I keep-caps |
| 181 |
support. The way to activate it using this program is with this |
| 182 |
argument. Setting the value to 1 will cause |
| 183 |
.I keep-caps |
| 184 |
to be active. Setting it to 0 will cause keep-caps to deactivate for |
| 185 |
the current process. In all cases, |
| 186 |
.I keep-caps |
| 187 |
is deactivated when an |
| 188 |
.BR exec () |
| 189 |
is performed. See |
| 190 |
.BR \-\-secbits and \-\-mode |
| 191 |
for ways to disable this feature. |
| 192 |
.TP |
| 193 |
.BI \-\-secbits= N |
| 194 |
Set the security-bits for the program. |
| 195 |
This is done using the |
| 196 |
.BR prctl (2) |
| 197 |
.B PR_SET_SECUREBITS |
| 198 |
operation. The list of supported bits and their meaning can be found |
| 199 |
in the |
| 200 |
.B <sys/secbits.h> |
| 201 |
header file. The program will list these bits via the |
| 202 |
.B \-\-print |
| 203 |
command. The argument is expressed as a numeric bitmask, in any of |
| 204 |
the formats permitted by |
| 205 |
.BR strtoul (3). |
| 206 |
An alternative to this bit-twiddling is embedded in the |
| 207 |
.B \-\-mode* |
| 208 |
commandline arguments. |
| 209 |
.TP |
| 210 |
.BI \-\-chroot= /some/path |
| 211 |
Execute the |
| 212 |
.BR chroot (2) |
| 213 |
system call with the new root-directory (/) equal to |
| 214 |
.IR path . |
| 215 |
This operation requires |
| 216 |
.B CAP_SYS_CHROOT |
| 217 |
to be in effect. |
| 218 |
.TP |
| 219 |
.BI \-\-forkfor= sec |
| 220 |
This command causes the program to fork a child process for so many |
| 221 |
seconds. The child will sleep that long and then exit with status |
| 222 |
0. The purpose of this command is to support exploring the way |
| 223 |
processes are killable in the face of capability changes. See the |
| 224 |
.B \-\-killit |
| 225 |
command. Only one fork can be active at a time. |
| 226 |
.TP |
| 227 |
.BI \-\-killit= sig |
| 228 |
This commands causes a |
| 229 |
.B \-\-forkfor |
| 230 |
child to be |
| 231 |
.BR kill (2)d |
| 232 |
with the specified signal. The command then waits for the child to exit. |
| 233 |
If the exit status does not match the signal being used to kill it, the |
| 234 |
.B capsh |
| 235 |
program exits with status 1. |
| 236 |
.TP |
| 237 |
.BI \-\-explain= cap_xxx |
| 238 |
Give a brief textual description of what privileges the specified |
| 239 |
capability makes available to a running program. Note, instead of |
| 240 |
\fIcap_xxx\fP, one can provide a decimal number and \fBcapsh\fP will |
| 241 |
look up the corresponding capability's description. |
| 242 |
.TP |
| 243 |
.BI \-\-shell =/full/path |
| 244 |
This option changes the shell that is invoked when the argument |
| 245 |
\fB==\fP is encountered. |
| 246 |
.TP |
| 247 |
.BI \-\-strict |
| 248 |
This option toggles the suppression of subsequent attempts to fixup |
| 249 |
\fB\-\-caps=\fP and \fB\-\-inh=\fP arguments. That is, when the |
| 250 |
prevailing Effective flag does not contain \fBCAP_SETPCAP\fB the to be |
| 251 |
raised Inheritable Flag values (in strict mode) are limited to those |
| 252 |
in the Permitted set. The strict mode defaults to off. Supplying this |
| 253 |
argument an even number of times restores this default behavior. |
| 254 |
.TP |
| 255 |
.BI \-\-suggest= phrase |
| 256 |
Scan each of the textual descriptions of capabilities, known to |
| 257 |
\fBcapsh\fP, and display all descriptions that include \fIphrase\fP. |
| 258 |
.TP |
| 259 |
.BI \-\-decode= N |
| 260 |
This is a convenience feature. If you look at |
| 261 |
.B /proc/1/status |
| 262 |
there are some capability related fields of the following form: |
| 263 |
.nf |
| 264 |
|
| 265 |
CapInh: 0000000000000000 |
| 266 |
CapPrm: 0000003fffffffff |
| 267 |
CapEff: 0000003fffffffff |
| 268 |
CapBnd: 0000003fffffffff |
| 269 |
CapAmb: 0000000000000000 |
| 270 |
|
| 271 |
.fi |
| 272 |
This option provides a quick way to decode a capability vector |
| 273 |
represented in this hexadecimal form. |
| 274 |
Here's an example that decodes the two lowest capability bits: |
| 275 |
.IP |
| 276 |
.nf |
| 277 |
$ \fBcapsh \-\-decode=3\fP |
| 278 |
0x0000000000000003=cap_chown,cap_dac_override |
| 279 |
.fi |
| 280 |
.TP |
| 281 |
.BI \-\-supports= xxx |
| 282 |
As the kernel evolves, more capabilities are added. This option can be used |
| 283 |
to verify the existence of a capability on the system. For example, |
| 284 |
.BI \-\-supports= cap_syslog |
| 285 |
will cause |
| 286 |
.B capsh |
| 287 |
to promptly exit with a status of 1 when run on |
| 288 |
kernel 2.6.27. However, when run on kernel 2.6.38 it will silently |
| 289 |
succeed. |
| 290 |
.TP |
| 291 |
.BI \-\-has\-p= xxx |
| 292 |
Exit with status 1 unless the |
| 293 |
.I permitted |
| 294 |
vector has capability |
| 295 |
.B xxx |
| 296 |
raised. |
| 297 |
.TP |
| 298 |
.B \-\-has\-ambient |
| 299 |
Performs a check to see if the running kernel supports ambient |
| 300 |
capabilities. If not, |
| 301 |
.B capsh |
| 302 |
exits with status 1. |
| 303 |
.TP |
| 304 |
.BI \-\-has\-a= xxx |
| 305 |
Exit with status 1 unless the |
| 306 |
.I ambient |
| 307 |
vector has capability |
| 308 |
.B xxx |
| 309 |
raised. |
| 310 |
.TP |
| 311 |
.BI \-\-has\-b= xxx |
| 312 |
Exit with status 1 unless the |
| 313 |
.I bounding |
| 314 |
vector has capability |
| 315 |
.B xxx |
| 316 |
in its (default) non-blocked state. |
| 317 |
.TP |
| 318 |
.BI \-\-iab= xxx |
| 319 |
Attempts to set the IAB tuple of inheritable capability vectors. |
| 320 |
The text conventions used for \fIxxx\fP are those of |
| 321 |
.BR cap_iab_from_text (3), |
| 322 |
and described in |
| 323 |
.BR cap_text_formats (7). |
| 324 |
.TP |
| 325 |
.BI \-\-addamb= xxx |
| 326 |
Adds the specified ambient capability to the running process. |
| 327 |
.TP |
| 328 |
.BI \-\-delamb= xxx |
| 329 |
Removes the specified ambient capability from the running process. |
| 330 |
.TP |
| 331 |
.B \-\-noamb |
| 332 |
Drops all ambient capabilities from the running process. |
| 333 |
.TP |
| 334 |
.B \-\-noenv |
| 335 |
Suppresses overriding of the HOME and USER environment variables when |
| 336 |
a subsequent |
| 337 |
.B \-\-user |
| 338 |
argument is processed. |
| 339 |
.TP |
| 340 |
.B \-\-quiet |
| 341 |
This argument is ignored unless it is the first one. If present, it |
| 342 |
suppresses the capsh runtime check to confirm the running libcap is |
| 343 |
recent enough that it can name all of the kernel supported capability |
| 344 |
values. |
| 345 |
.SH "EXIT STATUS" |
| 346 |
Following successful execution, |
| 347 |
.B capsh |
| 348 |
exits with status 0. Following |
| 349 |
an error, |
| 350 |
.B capsh |
| 351 |
immediately exits with status 1. |
| 352 |
.SH AUTHOR |
| 353 |
Written by Andrew G. Morgan <[email protected]>. |
| 354 |
.SH "REPORTING BUGS" |
| 355 |
Please report bugs via: |
| 356 |
.TP |
| 357 |
https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757 |
| 358 |
.SH "SEE ALSO" |
| 359 |
.BR libcap (3), |
| 360 |
.BR cap_from_text (3), |
| 361 |
.BR cap_iab (3), |
| 362 |
.BR cap_text_formats (7), |
| 363 |
.BR capabilities (7), |
| 364 |
.BR captree (8), |
| 365 |
.BR getcap (8), |
| 366 |
.BR getpcaps (8), |
| 367 |
and |
| 368 |
.BR setcap (8). |