mud.yang.go

Generated Go code for working with Manufacturer Usage Descriptions (MUDs).

Description

This repository contains a package with generated Go code for working with Manufacturer Usage Descriptions (MUDs, RFC 8520). The code is generated by openconfig/ygot which uses openconfig/goyang for parsing and compiling YANG files. The (required) YANG files were sourced from yangmodels/yang.

Usage

CLI

The main program in this repository contains several utility commands for working with MUD files. These (currently) include reading and validating MUD files against the YANG specification for MUDs. Cobra is used as the framework for the CLI application. It can be used as follows:

# validate a MUD file against the YANG specification
$ go run main.go validate ./examples/amazonEchoMud.json

# read (which includes validation) and print the MUD file
$ go run main.go read ./examples/amazonEchoMud.json

Library

Import the generated code as a library:

go get github.com/hslatman/mud.yang.go/pkg/mudyang

And use it:

package main

import (
    "fmt"
	"io/ioutil"

	"github.com/hslatman/mud.yang.go/pkg/mudyang"
)

func main() {

	json, _ := ioutil.ReadFile("./examples/lightbulb2000.json")
	mud := &mudyang.Mudfile{}
	if err := mudyang.Unmarshal([]byte(json), mud); err != nil {
		panic(fmt.Sprintf("Can't unmarshal JSON: %v", err))
	}

	println(*mud.Mud.MudUrl)
	println(*mud.Mud.MudVersion)
	println(mud.Mud.MudSignature)

	for k, v := range loadd.Acls.Acl {
		println(k, v)
	}

}

Examples

Currently four example MUD files are provided in this repository:

• lightbulb2000.json. The example from RFC 8520.
• amazonEchoMud.json. Source: https://iotanalytics.unsw.edu.au/mudprofiles (with modifications)
• wemoswitchMud.json. Source: https://iotanalytics.unsw.edu.au/mudprofiles (with modifications)
• invalidAmazonEchoMud.json. Source: https://iotanalytics.unsw.edu.au/mudprofiles (without modifications)

The MUD files for Amazon Echo and the WeMo Switch have been manually updated to conform to the current version of the RFC and/or make them valid MUD files according to the code generated by openconfig/ygot. These changes included changing the following fields:

• ietf-access-control-list:access-lists -> ietf-access-control-list:acls
• ethernet-acl-type -> eth-acl-type
• ethertypes hex string values to integers

Development

An early version of a custom generator for the generated Go code from YANG is available as a command in the main program in this repository. It can be used as follows:

# run the mudyang.go generator
$ go run main.go generate

There's a small caveat to running this command, though:

When an invalid pkg/mudyang.go file is generated, Go will complain about this in the next run. This can be fixed by resetting the changes and making sure that all input files are OK.

Manual Generation

You need the most recent version of ygot to run the code generation, because support for multiple bases, which the MUD YANG model uses, was only recently added.

The command to generate mudyang.go manually is as follows:

# within a local clone of the ygot source, assuming relative path(s) to hslatman/mud.yang.go:
go run generator/generator.go -path=./../../hslatman/mud.yang.go/yang \
-output_file=./../../hslatman/mud.yang.go/pkg/mudyang/mudyang.go \
-package_name=mudyang -generate_fakeroot -fakeroot_name=mudfile \
./../../hslatman/mud.yang.go/yang/ietf-packet-fields@2019-03-04.yang \
./../../hslatman/mud.yang.go/yang/ietf-ethertypes@2019-03-04.yang \
./../../hslatman/mud.yang.go/yang/ietf-acldns.yang \
./../../hslatman/mud.yang.go/yang/ietf-inet-types.yang \
./../../hslatman/mud.yang.go/yang/ietf-access-control-list.yang \
./../../hslatman/mud.yang.go/yang/ietf-mud@2019-01-28.yang

NOTE: despite the fact of specifying the path to scan for YANG files to include, this did not seem to work, which is why I've included the other required YANG files before the MUD YANG file.

A shorter variant that works, specifying only one additional YANG file instead of five, is the following:

# within a local clone of the ygot source, assuming relative path(s) to hslatman/mud.yang.go:
go run generator/generator.go -path=./../../hslatman/mud.yang.go/yang \
-output_file=./../../hslatman/mud.yang.go/pkg/mudyang/mudyang.go \
-package_name=mudyang -generate_fakeroot -fakeroot_name=mudfile \
./../../hslatman/mud.yang.go/yang/ietf-acldns.yang \
./../../hslatman/mud.yang.go/yang/ietf-mud@2019-01-28.yang

Without specifying the additional YANG file, the following error occurs:

Can't unmarshal JSON: parent container ipv4 (type *mudyang.IETFAccessControlList_Acls_Acl_Aces_Ace_Matches_Ipv4): JSON contains unexpected field ietf-acldns:dst-dnsname

TODOs

• Add yangmodels/yang as a git submodule?
• Add tests?
• Add utility functions in a wrapper of pkg/mudyang
• Look into path structs functionality of ygot generator