---
# host-runtime-detection / linux / t0 "Quick start"
#
# Falco on plain Linux hosts, outside any cluster, with three rules for what
# responders chase on servers: a web or application server starting a shell,
# cloud credential files read by a program that should not need them, and a
# download tool fetching the instance's credentials from the metadata
# service. Alerts go to syslog as JSON, where the host log template forwards
# them.
#
# Falco publishes a new package with every release. From
# download.falco.org/packages, pick the .deb or .rpm for these hosts, check
# it, and set the two values under vars.
#
# Run:
#   ansible-playbook -i inventory.ini playbook.yml
#
# Verify, on a test host in the cloud:
#   curl -s http://169.254.169.254/ > /dev/null
#   journalctl -t falco --since "5 min ago" | grep "Instance credentials"

- name: Watch hosts for what attackers do after they get in
  hosts: all
  become: true
  gather_facts: true

  vars:
    falco_package_url: "" # change me: the .deb or .rpm for these hosts
    falco_package_sha256: "" # change me: its SHA-256
    # Read by the package's install script: no prompts, the modern eBPF
    # driver, and no automatic rules updates, so the rules running are the
    # rules reviewed here.
    falco_install_env:
      FALCO_FRONTEND: noninteractive
      FALCO_DRIVER_CHOICE: modern_ebpf
      FALCOCTL_ENABLED: "no"

  tasks:
    - name: Stop if the package or its checksum was not set
      ansible.builtin.assert:
        that:
          - falco_package_url is match('https://.+\.(deb|rpm)$')
          - falco_package_sha256 | length == 64
        fail_msg: Set falco_package_url to the .deb or .rpm, and falco_package_sha256 to its SHA-256.

    - name: Download Falco, refusing it if the checksum differs
      ansible.builtin.get_url:
        url: "{{ falco_package_url }}"
        dest: "/var/tmp/{{ falco_package_url | basename }}"
        checksum: "sha256:{{ falco_package_sha256 }}"
        mode: "0644"

    - name: Install it (Debian and Ubuntu)
      ansible.builtin.apt:
        deb: "/var/tmp/{{ falco_package_url | basename }}"
      environment: "{{ falco_install_env }}"
      when: falco_package_url.endswith('.deb')
      notify: Restart Falco

    - name: Install it (Red Hat family)
      ansible.builtin.dnf:
        name: "/var/tmp/{{ falco_package_url | basename }}"
        state: present
      environment: "{{ falco_install_env }}"
      when: falco_package_url.endswith('.rpm')
      notify: Restart Falco

    - name: Send alerts to syslog as JSON
      ansible.builtin.copy:
        dest: /etc/falco/config.d/50-iac.yaml
        owner: root
        group: root
        mode: "0644"
        content: |
          # Managed by Ansible.
          json_output: true
          syslog_output:
            enabled: true
      notify: Restart Falco

    - name: Write the host rules
      ansible.builtin.copy:
        dest: /etc/falco/rules.d/50-iac-host.yaml
        owner: root
        group: root
        mode: "0644"
        content: |
          # Managed by Ansible. These build on the macros in Falco's default
          # rules, such as spawned_process, shell_procs, open_read, outbound.

          - list: iac_network_services
            items: [nginx, httpd, apache2, php-fpm, java, node, gunicorn, uwsgi, tomcat]

          - rule: Shell started by a network service
            desc: >-
              A web or application server started a shell. That is what a web
              shell or a command injection looks like from the host.
            condition: spawned_process and shell_procs and proc.pname in (iac_network_services)
            output: >-
              Shell started by a network service
              (parent=%proc.pname command=%proc.cmdline user=%user.name host=%evt.hostname)
            priority: CRITICAL
            tags: [host, mitre_execution]

          # Programs expected to read the credential files. python3 is here
          # because SDK-based tools run under it; take it out where none do.
          - list: iac_cloud_credential_readers
            items: [aws, gcloud, python3, terraform, tofu, az]

          - rule: Cloud credentials read by an unexpected program
            desc: >-
              A program other than the cloud tools read a stored cloud
              credential file.
            condition: >-
              open_read
              and (fd.name endswith "/.aws/credentials" or fd.name contains "/.config/gcloud/")
              and not proc.name in (iac_cloud_credential_readers)
            output: >-
              Cloud credentials read by an unexpected program
              (file=%fd.name program=%proc.name command=%proc.cmdline user=%user.name)
            priority: WARNING
            tags: [host, credentials, mitre_credential_access]

          - rule: Instance credentials fetched by a download tool
            desc: >-
              A download tool connected to the instance metadata service,
              which is how stolen instance credentials are usually fetched.
            condition: outbound and fd.sip="169.254.169.254" and proc.name in (curl, wget, nc, ncat, socat)
            output: >-
              Instance credentials fetched by a download tool
              (program=%proc.name command=%proc.cmdline user=%user.name)
            priority: WARNING
            tags: [host, credentials, mitre_credential_access]
      notify: Restart Falco

    - name: Make sure Falco is enabled and running
      ansible.builtin.service:
        name: falco-modern-bpf
        enabled: true
        state: started

  handlers:
    - name: Restart Falco
      ansible.builtin.service:
        name: falco-modern-bpf
        state: restarted
