mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-04 16:35:02 +01:00
308 lines
9.5 KiB
Text
308 lines
9.5 KiB
Text
# This publication is intellectual property of Canonical Ltd. Its contents
|
|
# can be duplicated, either in part or in whole, provided that a copyright
|
|
# label is visibly located on each copy.
|
|
#
|
|
# All information found in this book has been compiled with utmost
|
|
# attention to detail. However, this does not guarantee complete accuracy.
|
|
# Neither Canonical Ltd, the authors, nor the translators shall be held
|
|
# liable for possible errors or the consequences thereof.
|
|
#
|
|
# Many of the software and hardware descriptions cited in this book
|
|
# are registered trademarks. All trade names are subject to copyright
|
|
# restrictions and may be registered trade marks. Canonical Ltd
|
|
# essentially adheres to the manufacturer's spelling.
|
|
#
|
|
# Names of products and trademarks appearing in this book (with or without
|
|
# specific notation) are likewise subject to trademark and trade protection
|
|
# laws and may thus fall under copyright restrictions.
|
|
#
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
aa-easyprof - AppArmor profile generation made easy.
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<aa-easyprof> [option] E<lt>path to binaryE<gt>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<aa-easyprof> provides an easy to use interface for AppArmor policy
|
|
generation. B<aa-easyprof> supports the use of templates and policy groups to
|
|
quickly profile an application. Please note that while this tool can help
|
|
with policy generation, its utility is dependent on the quality of the
|
|
templates, policy groups and abstractions used. Also, this tool may create
|
|
policy which is less restricted than creating policy by hand or with
|
|
B<aa-genprof> and B<aa-logprof>.
|
|
|
|
=head1 OPTIONS
|
|
|
|
B<aa-easyprof> accepts the following arguments:
|
|
|
|
=over 4
|
|
|
|
=item -t TEMPLATE, --template=TEMPLATE
|
|
|
|
Specify which template to use. May specify either a system template from
|
|
/usr/share/apparmor/easyprof/templates or a filename for the template to
|
|
use. If not specified, use /usr/share/apparmor/easyprof/templates/default.
|
|
|
|
=item -p POLICYGROUPS, --policy-groups=POLICYGROUPS
|
|
|
|
Specify POLICY as a comma-separated list of policy groups. See --list-templates
|
|
for supported policy groups. The available policy groups are in
|
|
/usr/share/apparmor/easyprof/policy. Policy groups are simply groupings of
|
|
AppArmor rules or policies. They are similar to AppArmor abstractions, but
|
|
usually encompass more policy rules.
|
|
|
|
=item -a ABSTRACTIONS, --abstractions=ABSTRACTIONS
|
|
|
|
Specify ABSTRACTIONS as a comma-separated list of AppArmor abstractions. It is
|
|
usually recommended you use policy groups instead, but this is provided as a
|
|
convenience. AppArmor abstractions are located in /etc/apparmor.d/abstractions.
|
|
See apparmor.d(5) for details.
|
|
|
|
=item -r PATH, --read-path=PATH
|
|
|
|
Specify a PATH to allow owner reads. May be specified multiple times. If the
|
|
PATH ends in a '/', then PATH is treated as a directory and reads are allowed
|
|
to all files under this directory. Can optionally use '/*' at the end of the
|
|
PATH to only allow reads to files directly in PATH.
|
|
|
|
=item -w PATH, --write-dir=PATH
|
|
|
|
Like --read-path but also allow owner writes in additions to reads.
|
|
|
|
=item -n NAME, --name=NAME
|
|
|
|
Specify NAME of policy. If not specified, NAME is set to the name of the
|
|
binary. The NAME of the policy is typically only used for profile meta
|
|
data and does not specify the AppArmor profile name.
|
|
|
|
=item --profile-name=PROFILENAME
|
|
|
|
Specify the AppArmor profile name. When set, uses 'profile PROFILENAME' in the
|
|
profile. When set and specifying a binary, uses 'profile PROFILENAME BINARY'
|
|
in the profile. If not set, the binary will be used as the profile name and
|
|
profile attachment.
|
|
|
|
=item --template-var="@{VAR}=VALUE"
|
|
|
|
Set VAR to VALUE in the resulting policy. This typically only makes sense if
|
|
the specified template uses this value. May be specified multiple times.
|
|
|
|
=item --list-templates
|
|
|
|
List available templates.
|
|
|
|
=item --show-template
|
|
|
|
Display template specified with --template.
|
|
|
|
=item --templates-dir=PATH
|
|
|
|
Use PATH instead of system templates directory.
|
|
|
|
=item --include-templates-dir=PATH
|
|
|
|
Include PATH when searching for templates in addition to the system templates
|
|
directory (or the one specified with --templates-dir). System templates will
|
|
match before those in PATH.
|
|
|
|
=item --list-policy-groups
|
|
|
|
List available policy groups.
|
|
|
|
=item --show-policy-group
|
|
|
|
Display policy groups specified with --policy-groups.
|
|
|
|
=item --policy-groups-dir=PATH
|
|
|
|
Use PATH instead of system policy-groups directory.
|
|
|
|
=item --include-policy-groups-dir=PATH
|
|
|
|
Include PATH when searching for policy groups in addition to the system
|
|
policy-groups directory (or the one specified with --policy-groups-dir). System
|
|
policy-groups will match before those in PATH.
|
|
|
|
=item --policy-version=VERSION
|
|
|
|
Must be used with --policy-vendor and is used to specify the version of policy
|
|
groups and templates. When specified, B<aa-easyprof> looks for the subdirectory
|
|
VENDOR/VERSION within the policy-groups and templates directory. The specified
|
|
version must be a positive decimal number compatible with the JSON Number type.
|
|
Eg, when using:
|
|
|
|
|
|
$ aa-easyprof --templates-dir=/usr/share/apparmor/easyprof/templates \
|
|
--policy-groups-dir=/usr/share/apparmor/easyprof/policygroups \
|
|
--policy-vendor="foo" \
|
|
--policy-version=1.0
|
|
|
|
Then /usr/share/apparmor/easyprof/templates/foo/1.0 will be searched for
|
|
templates and /usr/share/apparmor/easyprof/policygroups/foo/1.0 for policy
|
|
groups.
|
|
|
|
=item --policy-vendor=VENDOR
|
|
|
|
Must be used with --policy-version and is used to specify the vendor for policy
|
|
groups and templates. See --policy-version for more information.
|
|
|
|
=item --author
|
|
|
|
Specify author of the policy.
|
|
|
|
=item --copyright
|
|
|
|
Specify copyright of the policy.
|
|
|
|
=item --comment
|
|
|
|
Specify comment for the policy.
|
|
|
|
=item -m MANIFEST, --manifest=MANIFEST
|
|
|
|
B<aa-easyprof> also supports using a JSON manifest file for specifying options
|
|
related to policy. Unlike command line arguments, the JSON file may specify
|
|
multiple profiles. The structure of the JSON is:
|
|
|
|
{
|
|
"security": {
|
|
"profiles": {
|
|
"<profile name 1>": {
|
|
... attributes specific to this profile ...
|
|
},
|
|
"<profile name 2>": {
|
|
...
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
Each profile JSON object (ie, everything under a profile name) may specify any
|
|
fields related to policy. The "security" JSON container object is optional and
|
|
may be omitted. An example manifest file demonstrating all fields is:
|
|
|
|
{
|
|
"security": {
|
|
"profiles": {
|
|
"com.example.foo": {
|
|
"abstractions": [
|
|
"audio",
|
|
"gnome"
|
|
],
|
|
"author": "Your Name",
|
|
"binary": "/opt/foo/**",
|
|
"comment": "Unstructured single-line comment",
|
|
"copyright": "Unstructured single-line copyright statement",
|
|
"name": "My Foo App",
|
|
"policy_groups": [
|
|
"networking",
|
|
"user-application"
|
|
],
|
|
"policy_vendor": "somevendor",
|
|
"policy_version": 1.0,
|
|
"read_path": [
|
|
"/tmp/foo_r",
|
|
"/tmp/bar_r/"
|
|
],
|
|
"template": "user-application",
|
|
"template_variables": {
|
|
"APPNAME": "foo",
|
|
"VAR1": "bar",
|
|
"VAR2": "baz"
|
|
},
|
|
"write_path": [
|
|
"/tmp/foo_w",
|
|
"/tmp/bar_w/"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
A manifest file does not have to include all the fields. Eg, a manifest file
|
|
for an Ubuntu SDK application might be:
|
|
|
|
{
|
|
"security": {
|
|
"profiles": {
|
|
"com.ubuntu.developer.myusername.MyCoolApp": {
|
|
"policy_groups": [
|
|
"networking",
|
|
"online-accounts"
|
|
],
|
|
"policy_vendor": "ubuntu",
|
|
"policy_version": 1.0,
|
|
"template": "ubuntu-sdk",
|
|
"template_variables": {
|
|
"APPNAME": "MyCoolApp",
|
|
"APPVERSION": "0.1.2"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
=item --verify-manifest
|
|
|
|
When used with --manifest, warn about potentially unsafe definitions in the
|
|
manifest file.
|
|
|
|
=item --output-format=FORMAT
|
|
|
|
Specify either B<text> (default if unspecified) for AppArmor policy output or
|
|
B<json> for JSON manifest format.
|
|
|
|
=item --output-directory=DIR
|
|
|
|
Specify output directory for profile. If unspecified, policy is sent to stdout.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Example usage for a program named 'foo' which is installed in /opt/foo:
|
|
|
|
$ aa-easyprof --template=user-application --template-var="@{APPNAME}=foo" \
|
|
--policy-groups=opt-application,user-application \
|
|
/opt/foo/bin/FooApp
|
|
|
|
When using a manifest file:
|
|
|
|
$ aa-easyprof --manifest=manifest.json
|
|
|
|
To output a manifest file based on aa-easyprof arguments:
|
|
|
|
$ aa-easyprof --output-format=json \
|
|
--author="Your Name" \
|
|
--comment="Unstructured single-line comment" \
|
|
--copyright="Unstructured single-line copyright statement" \
|
|
--name="My Foo App" \
|
|
--profile-name="com.example.foo" \
|
|
--template="user-application" \
|
|
--policy-groups="user-application,networking" \
|
|
--abstractions="audio,gnome" \
|
|
--read-path="/tmp/foo_r" \
|
|
--read-path="/tmp/bar_r/" \
|
|
--write-path="/tmp/foo_w" \
|
|
--write-path=/tmp/bar_w/ \
|
|
--template-var="@{APPNAME}=foo" \
|
|
--template-var="@{VAR1}=bar" \
|
|
--template-var="@{VAR2}=baz" \
|
|
"/opt/foo/**"
|
|
|
|
=head1 BUGS
|
|
|
|
If you find any additional bugs, please report them to Launchpad at
|
|
L<https://bugs.launchpad.net/apparmor/+filebug>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
apparmor(7) apparmor.d(5)
|
|
|
|
=cut
|