Debian Codegraph @

doc/capsh.1

raw
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).