.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Alien::Build::Manual::Security 3"
.TH Alien::Build::Manual::Security 3 "2024-10-29" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Alien::Build::Manual::Security \- General alien author documentation
.SH "VERSION"
.IX Header "VERSION"
version 2.84
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& perldoc Alien::Build::Manual::Security
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
You are rightly concerned that an Alien might be downloading something random
off the internet.  This manual will describe some of the real risks and go over
how you can mitigate them.
.SS "no warranty"
.IX Subsection "no warranty"
Alien::Build provides Alien authors with tools to add external non-Perl
dependencies to \s-1CPAN\s0 modules.  It is open source software that is entirely
volunteer driven, meaning the people writing this software are not getting
compensated monetarily for the work.  As such, we do our best not to
intentionally introduce security vulnerabilities into our modules, or their
dependencies.  But it is also not our responsibility either.  If you are
operating in an environment where you need absolute security, you need to
carefully audit \fIall\fR of the software that you use.
.SS "Alien::Build vs. \s-1CPAN\s0"
.IX Subsection "Alien::Build vs. CPAN"
I suppose you could argue that Alien::Build based Aliens and Aliens
in general are inherently less secure than the the Perl modules on \s-1CPAN\s0
that don't download random stuff off the internet.  Worse yet, Aliens
might be downloading from insecure sources like \f(CW\*(C`http\*(C'\fR or \f(CW\*(C`ftp\*(C'\fR.
.PP
This argument falls apart pretty quickly when you realize that
.IP "1." 4
Perl modules from \s-1CPAN\s0 are in fact random stuff off the internet.
Most modules, when installed execute a \f(CW\*(C`Makefile.PL\*(C'\fR which can execute
completely arbitrary Perl code.  Without a proper audit or firewalls
that \s-1CPAN\s0 code could be making connections to insecure sources
like \f(CW\*(C`http\*(C'\fR if they are not themselves doing something nefarious.
.IP "2." 4
By default, the most frequently used \s-1CPAN\s0 client App::cpanminus
uses \f(CW\*(C`http\*(C'\fR to fetch \s-1CPAN\s0 modules.  So unless you have specifically
configured it to connect to a secure source you are downloading
even more random stuff than usual off the internet.
.PP
The \s-1TL\s0;DR is that if you are using a Perl module, whether it be
\&\f(CW\*(C`Foo::PP\*(C'\fR, \f(CW\*(C`Foo::XS\*(C'\fR or \f(CW\*(C`Alien::libfoo\*(C'\fR and you are concerned about
security you need to audit all of your Perl modules, not just the Alien
ones.
.SS "Restricting Alien::Build by environment"
.IX Subsection "Restricting Alien::Build by environment"
Okay, granted you need to audit software for security regardless of
if it is Alien, you still don't like the idea of downloading external
dependencies and you can't firewall just the \s-1CPAN\s0 module installs.
.PP
Alien::Build based Aliens respect a number of environment variables
that at least give you some control over how aggresive Alien::Build
will be at fetching random stuff off the internet.
.ie n .IP """ALIEN_DOWNLOAD_RULE""" 4
.el .IP "\f(CWALIEN_DOWNLOAD_RULE\fR" 4
.IX Item "ALIEN_DOWNLOAD_RULE"
This environment variable configures how Alien::Build will deal
with insecure protocols and files that do not include a cryptographic
signature.
.Sp
Part of the design of the Alien::Build system is that it typically
tries to download the latest version of a package instead of a fixed
version, so that the Alien doesn't need to be updated when a new
alienized package is released.  This means that we frequently have
to rely on \s-1TLS\s0 or bundled alienized packages to ensure that the
alienized package is fetched securely.
.Sp
Recently (as of Alien::Build 2.59) we started supporting cryptographic
signatures defined in alienfiles, but they are not yet very common,
and they only really work when a single alienized package \s-1URL\s0 is hard
coded into the alienfile instead of the more typical mode of operation
where the latest version is downloaded.
.RS 4
.IP "warn" 4
.IX Item "warn"
This mode will warn you if an Alien::Build based Alien attempts
to fetch a alienized package insecurely.  It will also warn you if
a package doesn't have a cryptographic signature.  Neither of these
things wild stop the Alien from being installed.
.Sp
This is unfortunately currently the default mode of Alien::Build,
for historical reasons.  Once plugins and Aliens are updated to
either use secure fetch (\s-1TLS\s0 or bundled alienized packages), or
cryptographic signatures, the default will be changed to
\&\f(CW\*(C`digest_or_encrypt\*(C'\fR.
.IP "digest_or_encrypt" 4
.IX Item "digest_or_encrypt"
This mode will require that before an alienized package is extracted
that it is either fetched via a secure protocol (\f(CW\*(C`http\*(C'\fR or \f(CW\*(C`file\*(C'\fR),
or the package matches a cryptographic signature.
.Sp
This will likely be the default for Alien::Build in the near future,
but it doesn't hurt to set it now, if you don't mind submitting
tickets to Aliens or plugins that don't
support this mode yet.
.RE
.RS 4
.RE
.ie n .IP """ALIEN_INSTALL_NETWORK""" 4
.el .IP "\f(CWALIEN_INSTALL_NETWORK\fR" 4
.IX Item "ALIEN_INSTALL_NETWORK"
By design Aliens should use local installs of libraries and tools
before downloading source from the internet.  Setting this environment
variable to false, will instruct Alien::Build to not attempt to
fetch the alienized package off the internet if it is not available
locally or as a bundled package.
.Sp
This is similar to setting \f(CW\*(C`ALIEN_INSTALL_TYPE\*(C'\fR to \f(CW\*(C`system\*(C'\fR (see
below), except it does allow Aliens that bundle their alienized
package inside the \s-1CPAN\s0 package tarball.
.Sp
Some Aliens will not install properly at first, but when they error
you can install the system package and try to re-install the Alien.
.ie n .IP """ALIEN_INSTALL_TYPE""" 4
.el .IP "\f(CWALIEN_INSTALL_TYPE\fR" 4
.IX Item "ALIEN_INSTALL_TYPE"
Setting \f(CW\*(C`ALIEN_INSTALL_TYPE\*(C'\fR to \f(CW\*(C`system\*(C'\fR is similar to setting
\&\f(CW\*(C`ALIEN_INSTALL_NETWORK\*(C'\fR to false, except that bundled alienized
packages will also be rejected.  This environment variable is really
intended for use by operating system vendors packaging Aliens,
or for Alien developer testing (in \s-1CI\s0 for example).  For some
who want to restrict how Aliens install this might be the right
tool to reach for.
.PP
Note that this is definitely best effort.  If the Alien author makes
a mistake or is malicious they could override these environment variables
inside the \f(CW\*(C`Makefile.PL\*(C'\fR, so you still need to audit any software to
ensure that it doesn't fetch source off the internet.
.SS "Security Related Plugins"
.IX Subsection "Security Related Plugins"
There are a number of plugins that give the user or installer control
over how Alien::Build behaves, and may be useful for rudimentary
security.
.IP "Alien::Build::Plugin::Fetch::Prompt" 4
.IX Item "Alien::Build::Plugin::Fetch::Prompt"
This plugin will prompt before fetching any remote files.  This only
really works when you are installing Aliens interactively.
.IP "Alien::Build::Plugin::Fetch::HostAllowList" 4
.IX Item "Alien::Build::Plugin::Fetch::HostAllowList"
This plugin will only allow fetching from hosts that are in an allow list.
.IP "Alien::Build::Plugin::Fetch::HostBlockList" 4
.IX Item "Alien::Build::Plugin::Fetch::HostBlockList"
This plugin will not allow fetching from hosts that are in a block list.
.IP "Alien::Build::Plugin::Fetch::Rewrite" 4
.IX Item "Alien::Build::Plugin::Fetch::Rewrite"
This plugin can re-write fetched URLs before the request is made.  This
can be useful if you have a local mirror of certain sources that you
want to use instead of fetching from the wider internet.
.IP "Alien::Build::Plugin::Probe::Override" 4
.IX Item "Alien::Build::Plugin::Probe::Override"
This plugin can override the \f(CW\*(C`ALIEN_INSTALL_TYPE\*(C'\fR on a perl-Alien basis.
This can be useful if you want to install some Aliens in \f(CW\*(C`share\*(C'\fR
mode, but generally want to enforce \f(CW\*(C`system\*(C'\fR mode.
.SS "local configuration"
.IX Subsection "local configuration"
You can configure the way Alien::Build based Aliens are installed with the
local configuration file \f(CW\*(C`~/.alienbuild/rc.pl\*(C'\fR.  See Alien::Build::rc for
details.
.SH "CAVEATS"
.IX Header "CAVEATS"
This whole document is caveats, but if you haven't gotten it by now then,
fundamentally if you need to use Perl modules securely then you need to
audit the code for security vulnerabilities.  If you think that the security
of Alien::Build and the Aliens that depend on it, then \fIpatches welcome\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "Alien::Build::Manual" 4
.IX Item "Alien::Build::Manual"
Other Alien::Build manuals.
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Diab Jerius (\s-1DJERIUS\s0)
.PP
Roy Storey (\s-1KIWIROY\s0)
.PP
Ilya Pavlov
.PP
David Mertens (run4flat)
.PP
Mark Nunberg (mordy, mnunberg)
.PP
Christian Walde (Mithaldu)
.PP
Brian Wightman (MidLifeXis)
.PP
Zaki Mughal (zmughal)
.PP
mohawk (mohawk2, \s-1ETJ\s0)
.PP
Vikas N Kumar (vikasnkumar)
.PP
Flavio Poletti (polettix)
.PP
Salvador Fandiño (salva)
.PP
Gianni Ceccarelli (dakkar)
.PP
Pavel Shaydo (zwon, trinitum)
.PP
Kang-min Liu (劉康民, gugod)
.PP
Nicholas Shipp (nshp)
.PP
Juan Julián Merelo Guervós (\s-1JJ\s0)
.PP
Joel Berger (\s-1JBERGER\s0)
.PP
Petr Písař (ppisar)
.PP
Lance Wicks (\s-1LANCEW\s0)
.PP
Ahmad Fatoum (a3f, \s-1ATHREEF\s0)
.PP
José Joaquín Atria (\s-1JJATRIA\s0)
.PP
Duke Leto (\s-1LETO\s0)
.PP
Shoichi Kaji (\s-1SKAJI\s0)
.PP
Shawn Laffan (\s-1SLAFFAN\s0)
.PP
Paul Evans (leonerd, \s-1PEVANS\s0)
.PP
Håkon Hægland (hakonhagland, \s-1HAKONH\s0)
.PP
nick nauwelaerts (\s-1INPHOBIA\s0)
.PP
Florian Weimer
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011\-2022 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.