acsc_e8_office_hardening

Automate the enforcement of the ACSC essential eight Microsoft office macro security.

The module will restrict the use of macros within Office.

There are 4 operating modes

• All macros allowed - default mode
• All macros disabled - disable all macros in Office, most secure setting
• Only macros from trusted locations - Only permit macros from locations specified in the trusted_location parameter
• Only macros digitally signed by trusted publishers - Macros must be signed by a trusted publisher.

Please see ACSC documentation for more details. Saved link

Table of Contents

1. Description
2. Setup - The basics of getting started with acsc_e8_office_hardening
   • What acsc_e8_office_hardening affects
   • Setup requirements
   • Beginning with acsc_e8_office_hardening
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

Use this module to automate the enforcement of ACSC Essential 8 Office macro controls.

Setup

What acsc_e8_office_hardening affects

acsc_e8_office_hardening will add required registry settings to systems to restrict Office macros as required.

Most registry settings are applied to HKEY_USER. Due to this, Puppet will manage a significant number of resources as each user has their own registry hive. acsc_e8_office_hardening will also modify the default c:\users\Default\ntuser.dat. This is required for any new users who log on to the system. Without this, Puppet won't restrict that user until the next Puppet run. A suboptimal outcome. By default the module will mount and check the default ntuser.dat on each clean boot and every 24 hours thereafter.

Setup Requirements

Plugin sync is required for this module. Three facts will be automatically distributed

• office_macro_local_sids
• office_macro_last_run
• office_macro_uptime

Following forge modules are required

• puppetlabs-stdlib
• puppetlabs-registry

Beginning with acsc_e8_office_hardening

The very basic steps needed for a user to get the module up and running. This can include setup steps, if necessary, or it can be an example of the most basic use of the module.

Usage

In most basic form, non-enforcement mode.

include acsc_e8_office_hardening

Block all macros

  class {'acsc_e8_office_hardening':
    macro_setting       => 'all_macros_disabled',
  }

Permit macros from trusted location using a profile and hiera

class profile::office_hardening (
  Hash $trusted_locations = {}
){
  class {'acsc_e8_office_hardening':
    macro_setting       => 'macros_from_trusted_locations'',
    trusted_locations   => $trusted_locations,
  }
}

Corresponding hiera data

profile::office_hardening::trusted_locations:
  location1:
    path: 'c:\\temp'
    date: '12/12/2021 12:00 PM'
    description: 'Temp on c for macros'
    allowsub: true

Explanation of trusted_location hash

  location1: - Name of hash
    path: 'c:\\temp' - Path to allow (string)
    date: '12/12/2021 12:00 PM' - Date, use format as shown (string) (Optional)
    description: 'Temp on c for macros' - Description of location (string) (Optional)
    allowsub: true - Permit subdirectory true\false (boolean) (Optional)

Limitations

Supported office versions

• Office 365
• Office 2016
• Office 2019

Developed and tested on

• Windows 2019
• Office 365

Development

Please submit any issues to the issue tracker. Pull requests keenly accepted :)

Reference

Table of Contents

Classes

• acsc_e8_office_hardening: A module which enforces https://github.com/benjamin-robertson/acsc_e8_office_hardening/blob/main/PROTECT%20-%20Microsoft%20Office%20Macro%20S
• acsc_e8_office_hardening::clear_unused_registry_values: Private class
• acsc_e8_office_hardening::disable_flash: Private class
• acsc_e8_office_hardening::macros: Private class
• acsc_e8_office_hardening::mount_default_user_hive: Private class
• acsc_e8_office_hardening::trusted_locations: Private class
• acsc_e8_office_hardening::unmount_default_user_hive: Private class

Defined types

• acsc_e8_office_hardening::delete_trusted_location: Private type
• acsc_e8_office_hardening::delete_user_registry_value: Private type
• acsc_e8_office_hardening::set_trusted_location: Private type
• acsc_e8_office_hardening::user_registry_value: Private type

Classes

acsc_e8_office_hardening

A module which enforces https://github.com/benjamin-robertson/acsc_e8_office_hardening/blob/main/PROTECT%20-%20Microsoft%20Office%20Macro%20Security%20(October%202021).pdf

lint:ignore:140chars

Examples

include acsc_e8_office_hardening

Parameters

The following parameters are available in the acsc_e8_office_hardening class:

• disable_flash_content
• disable_macros
• set_ntuser_interval
• macro_setting
• trusted_locations

disable_flash_content

Data type: Boolean

Disable flash content. Default: false

Default value: false

disable_macros

Data type: Boolean

Disable macros, Default: true

Default value: true

set_ntuser_interval

Data type: Integer

Set the interval to set the default ntuser macro settings in hours. Default: 1

Default value: 24

macro_setting

Data type: Enum['all_macros_disabled','macros_from_trusted_locations','signed_macros_only','clear_macro_settings']

Macro settings to enforce, for details see ACSC publication. Default: clear_macro_settings

Default value: 'clear_macro_settings'

trusted_locations

Data type: Variant[Undef,Hash[String,Hash,1,20]]

Set trusted location. See example in readme. Default: undef

Default value: undef

acsc_e8_office_hardening::clear_unused_registry_values

Clear unused registry values when switching between office macro modes

Examples

class { 'acsc_e8_office_hardening::clear_unused_registry_values':
  system_setting     => $facts['office_macro_last_run'],
  configured_setting => $macro_setting,
}

Parameters

The following parameters are available in the acsc_e8_office_hardening::clear_unused_registry_values class:

• system_setting
• configured_setting

system_setting

Data type: String

Current system macro setting

configured_setting

Data type: String

Configured system macro setting

acsc_e8_office_hardening::disable_flash

Disables flash within office

Examples

include acsc_e8_office_hardening::disable_flash

Parameters

The following parameters are available in the acsc_e8_office_hardening::disable_flash class:

• reg_values

reg_values

Data type: Hash

registry values to set

acsc_e8_office_hardening::macros

Configured office macro settings for office. Private class

Examples

include acsc_e8_office_hardening::macros

Parameters

The following parameters are available in the acsc_e8_office_hardening::macros class:

• macro_setting

macro_setting

Data type: String

set office macro setting

Default value: 'clear_macro_settings'

acsc_e8_office_hardening::mount_default_user_hive

Mounts the default user ntuser.dat file located under c:\user\default\ntuser.dat Mounts under HKU\user_default Private class

Examples

include acsc_e8_office_hardening::mount_default_user_hive

acsc_e8_office_hardening::trusted_locations

Creates trusted locations for office Private class

Examples

include acsc_e8_office_hardening::trusted_locations

Parameters

The following parameters are available in the acsc_e8_office_hardening::trusted_locations class:

• trusted_locations

trusted_locations

Data type: Hash

Hash of trusted locations. See readme for example

acsc_e8_office_hardening::unmount_default_user_hive

Mounts the default user ntuser.dat file located under c:\user\default\ntuser.dat Mounts under HKU\user_default Private class

Examples

include acsc_e8_office_hardening::unmount_default_user_hive

Defined types

acsc_e8_office_hardening::delete_trusted_location

Delete trusted location if unmanaged by Pupppet We handle up to 20 custom locations

Examples

acsc_e8_office_hardening::delete_trusted_location { "location${delelete_index}":}

acsc_e8_office_hardening::delete_user_registry_value

Defined type which deletes registry value for each HKEY_CURRENT_USER on a machine.

Examples

acsc_e8_office_hardening::user_registry_value { 'key_name': }

Parameters

The following parameters are available in the acsc_e8_office_hardening::delete_user_registry_value defined type:

• key_name

key_name

Data type: String

key name to delete

acsc_e8_office_hardening::set_trusted_location

Creates trusted location for office files. This must be used in conjuntion with the macros_from_trusted_locations option. Otherwise it will have affect.

Examples

acsc_e8_office_hardening::set_trusted_location { 'namevar': }

Parameters

The following parameters are available in the acsc_e8_office_hardening::set_trusted_location defined type:

• path
• date
• description
• allowsub

path

Data type: String

File path to permit

date

Data type: Optional[Variant[String,Undef]]

Date set. Default: undef

Default value: undef

description

Data type: Optional[Variant[String,Undef]]

Description of path. Default: undef

Default value: undef

allowsub

Data type: Boolean

Permit sub directory under that path. Default: false

Default value: false

acsc_e8_office_hardening::user_registry_value

Defined type which sets registry value for each HKEY_CURRENT_USER on a machine.

Examples

acsc_e8_office_hardening::user_registry_value { 'namevar': }

Parameters

The following parameters are available in the acsc_e8_office_hardening::user_registry_value defined type:

• key_name
• key_details

key_name

Data type: String

key name

key_details

Data type: Hash

Key details, hash containing value, type and data for registry value

Changelog

All notable changes to this project will be documented in this file.

Release 1.0.0

Features

• Added support for Puppet 8, Server 2022 and Windows 11.
• Added Unit/lint testing to github actions.
• Removed use of legacy facts.
• Improved handling of office_macro_run time fact to prevent failures with strict mode.
• Bumped PDK version to 3.3.0.

Release 0.2.0

Features

• Republish to Forge.

Bugfixes

Known Issues

Release 0.1.1

Features

Bugfixes

• Fixed metadata.json to refer to the correct git repo and issue tracker.

Known Issues

Release 0.1.0

Features

Bugfixes

Known Issues