NAME

       Alien::Build::Manual::Security - General alien author documentation

VERSION

       version 2.80

SYNOPSIS

        perldoc Alien::Build::Manual::Security

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.

   no warranty
       Alien::Build provides Alien authors with tools to add external non-Perl dependencies to
       CPAN 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
       all of the software that you use.

   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 CPAN that don't download random stuff
       off the internet.  Worse yet, Aliens might be downloading from insecure sources like
       "http" or "ftp".

       This argument falls apart pretty quickly when you realize that

       1.  Perl modules from CPAN are in fact random stuff off the internet.  Most modules, when
           installed execute a "Makefile.PL" which can execute completely arbitrary Perl code.
           Without a proper audit or firewalls that CPAN code could be making connections to
           insecure sources like "http" if they are not themselves doing something nefarious.

       2.  By default, the most frequently used CPAN client App::cpanminus uses "http" to fetch
           CPAN 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.

       The TL;DR is that if you are using a Perl module, whether it be "Foo::PP", "Foo::XS" or
       "Alien::libfoo" and you are concerned about security you need to audit all of your Perl
       modules, not just the Alien ones.

   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 CPAN module installs.

       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.

       "ALIEN_DOWNLOAD_RULE"
           This environment variable configures how Alien::Build will deal with insecure
           protocols and files that do not include a cryptographic signature.

           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 TLS or bundled alienized packages to ensure that the
           alienized package is fetched securely.

           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 URL is hard coded into the alienfile instead of the
           more typical mode of operation where the latest version is downloaded.

           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.

               This is unfortunately currently the default mode of Alien::Build, for historical
               reasons.  Once plugins and Aliens are updated to either use secure fetch (TLS or
               bundled alienized packages), or cryptographic signatures, the default will be
               changed to "digest_or_encrypt".

           digest_or_encrypt
               This mode will require that before an alienized package is extracted that it is
               either fetched via a secure protocol ("http" or "file"), or the package matches a
               cryptographic signature.

               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.

       "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.

           This is similar to setting "ALIEN_INSTALL_TYPE" to "system" (see below), except it
           does allow Aliens that bundle their alienized package inside the CPAN package tarball.

           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.

       "ALIEN_INSTALL_TYPE"
           Setting "ALIEN_INSTALL_TYPE" to "system" is similar to setting "ALIEN_INSTALL_NETWORK"
           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 CI for example).  For some who want to
           restrict how Aliens install this might be the right tool to reach for.

       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 "Makefile.PL", so you
       still need to audit any software to ensure that it doesn't fetch source off the internet.

   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.

       Alien::Build::Plugin::Fetch::Prompt
           This plugin will prompt before fetching any remote files.  This only really works when
           you are installing Aliens interactively.

       Alien::Build::Plugin::Fetch::HostAllowList
           This plugin will only allow fetching from hosts that are in an allow list.

       Alien::Build::Plugin::Fetch::HostBlockList
           This plugin will not allow fetching from hosts that are in a block list.

       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.

       Alien::Build::Plugin::Probe::Override
           This plugin can override the "ALIEN_INSTALL_TYPE" on a perl-Alien basis.  This can be
           useful if you want to install some Aliens in "share" mode, but generally want to
           enforce "system" mode.

   local configuration
       You can configure the way Alien::Build based Aliens are installed with the local
       configuration file "~/.alienbuild/rc.pl".  See Alien::Build::rc for details.

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 patches welcome.

SEE ALSO

       Alien::Build::Manual
           Other Alien::Build manuals.

AUTHOR

       Author: Graham Ollis <plicease@cpan.org>

       Contributors:

       Diab Jerius (DJERIUS)

       Roy Storey (KIWIROY)

       Ilya Pavlov

       David Mertens (run4flat)

       Mark Nunberg (mordy, mnunberg)

       Christian Walde (Mithaldu)

       Brian Wightman (MidLifeXis)

       Zaki Mughal (zmughal)

       mohawk (mohawk2, ETJ)

       Vikas N Kumar (vikasnkumar)

       Flavio Poletti (polettix)

       Salvador Fandiño (salva)

       Gianni Ceccarelli (dakkar)

       Pavel Shaydo (zwon, trinitum)

       Kang-min Liu (劉康民, gugod)

       Nicholas Shipp (nshp)

       Juan Julián Merelo Guervós (JJ)

       Joel Berger (JBERGER)

       Petr Písař (ppisar)

       Lance Wicks (LANCEW)

       Ahmad Fatoum (a3f, ATHREEF)

       José Joaquín Atria (JJATRIA)

       Duke Leto (LETO)

       Shoichi Kaji (SKAJI)

       Shawn Laffan (SLAFFAN)

       Paul Evans (leonerd, PEVANS)

       Håkon Hægland (hakonhagland, HAKONH)

       nick nauwelaerts (INPHOBIA)

       Florian Weimer

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011-2022 by Graham Ollis.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.