1 // List the Macs that enrolled in Jamf Pro in the last few hours, with serial
2 // number, model and assigned user, flag the ones that need attention, and
3 // open one ticket for them. Returns a summary an automation can post to an
4 // alerts channel as is.
5 //
6 // Before publishing: replace acme. jamfcloud. com, here and in the `domains`
7 // export, with your Jamf Pro server as saved on Settings > Integrations >
8 // Jamf. The Jamf connection's API client needs the Read Computers privilege.
9
10 type NewMac = {
11 name : string ;
12 serial : string ;
13 model : string ;
14 email : string | null ;
15 fileVaultOn : boolean ;
16 managed : boolean ;
17 } ;
18
19 // The directory entry for an assigned email, or null when there is none.
20 type Person = { active : boolean } | null ;
21
22 export const input = z . object ( {
23 hours : z
24 . number ( )
25 . int ( )
26 . min ( 1 )
27 . max ( 168 )
28 . default ( 24 )
29 . describe ( "How many hours back to look for new enrollments, 1 to 168" ) ,
30 open_ticket_for_problems : z
31 . boolean ( )
32 . default ( true )
33 . describe ( "Open one ticket listing the new Macs that need attention" ) ,
34 } ) ;
35
36 // GET only. The org's Jamf connection authenticates every call.
37 export const domains = { "acme. jamfcloud. com" : "read" } ;
38
39 // Four pages of 50 keep the run well inside its time limit.
40 const PAGE_SIZE = 50 ;
41 const MAX_PAGES = 4 ;
42
43 const isObject = ( value : unknown ) : value is Record< string , unknown > =>
44 typeof value === "object" && value !== null ;
45
46 const getNested = ( value : unknown , path : string [ ] ) : unknown => {
47 let current : unknown = value ;
48 for ( const key of path ) {
49 if ( ! isObject ( current ) ) {
50 return undefined ;
51 }
52 current = current [ key ] ;
53 }
54 return current ;
55 } ;
56
57 const getString = ( value : unknown , path : string [ ] ) : string | null => {
58 const found = getNested ( value , path ) ;
59 return typeof found === "string" && found . trim ( ) !== "" ? found : null ;
60 } ;
61
62 const toMac = ( record : unknown ) : NewMac => ( {
63 name : getString ( record , [ "general" , "name" ] ) ?? "Unnamed Mac" ,
64 serial : getString ( record , [ "hardware" , "serialNumber" ] ) ?? "no serial" ,
65 model : getString ( record , [ "hardware" , "model" ] ) ?? "unknown model" ,
66 email : getString ( record , [ "userAndLocation" , "email" ] ) ,
67 fileVaultOn :
68 getNested ( record , [ "diskEncryption" , "fileVault2Enabled" ] ) === true ,
69 managed :
70 getNested ( record , [ "general" , "remoteManagement" , "managed" ] ) === true ,
71 } ) ;
72
73 // The new Macs on one page, newest first, and whether paging can stop: the
74 // page came back short, or it reached a Mac enrolled before the window.
75 const readPage = ( body : unknown , since : number ) => {
76 const records =
77 isObject ( body ) && Array . isArray ( body . results ) ? body . results : [ ] ;
78 const macs : NewMac [ ] = [ ] ;
79 let done = records . length < PAGE_SIZE ;
80 for ( const record of records ) {
81 const enrolled = Date . parse (
82 getString ( record , [ "general" , "lastEnrolledDate" ] ) ?? "" ,
83 ) ;
84 if ( enrolled >= since ) {
85 macs . push ( toMac ( record ) ) ;
86 } else if ( ! Number . isNaN ( enrolled ) ) {
87 done = true ;
88 }
89 }
90 return { macs , done } ;
91 } ;
92
93 const assignedEmails = ( macs : NewMac [ ] ) : string [ ] => [
94 . . . new Set ( macs . flatMap ( ( mac ) => ( mac . email === null ? [ ] : [ mac . email ] ) ) ) ,
95 ] ;
96
97 // find_users matches on substrings, so keep only the exact email.
98 const findPerson = (
99 matches : Array < { email : string ; active : boolean } > ,
100 email : string ,
101 ) : Person =>
102 matches . find ( ( user ) => user . email . toLowerCase ( ) === email . toLowerCase ( ) ) ??
103 null ;
104
105 const problemsFor = ( mac : NewMac , people : Map < string , Person > ) : string [ ] => {
106 const problems : string [ ] = [ ] ;
107 const person = mac . email === null ? null : ( people . get ( mac . email ) ?? null ) ;
108 if ( mac . email === null ) {
109 problems . push ( "no assigned user" ) ;
110 } else if ( person === null ) {
111 problems . push ( "assigned user not in the directory" ) ;
112 } else if ( ! person . active ) {
113 problems . push ( "assigned user is inactive" ) ;
114 }
115 if ( ! mac . fileVaultOn ) {
116 problems . push ( "FileVault off" ) ;
117 }
118 if ( ! mac . managed ) {
119 problems . push ( "not managed" ) ;
120 }
121 return problems ;
122 } ;
123
124 const macLine = ( mac : NewMac , people : Map < string , Person > ) : string => {
125 const problems = problemsFor ( mac , people ) ;
126 const user = mac . email ?? "no user" ;
127 const line = `• ${ mac . name } : ${ mac . serial } , ${ mac . model } , ${ user } ` ;
128 return problems . length === 0
129 ? line
130 : ` ${ line } . Needs: ${ problems . join ( ", " ) } ` ;
131 } ;
132
133 const plural = ( count : number , word : string ) : string =>
134 ` ${ count } ${ word } ${ count === 1 ? "" : "s" } ` ;
135
136 export default async function run ( params : z . infer < typeof input> ) {
137 // **List recently enrolled Macs**
138 // Jamf Pro returns the newest enrollments first, so paging stops early.
139 const since = Date . now ( ) - params . hours * 60 * 60 * 1000 ;
140 const macs : NewMac [ ] = [ ] ;
141 let done = false ;
142 for ( let page = 0 ; page < MAX_PAGES && ! done ; page ++ ) {
143 // A literal URL, so Risotto checks it against your Jamf server on save.
144 // The sections are the only parts of each record this check reads.
145 const response = await http . get (
146 "https://acme. jamfcloud. com/api/v4/computers-inventory?section=GENERAL§ion=HARDWARE§ion=USER_AND_LOCATION§ion=DISK_ENCRYPTION" ,
147 {
148 query : {
149 page : String ( page ) ,
150 "page-size" : String ( PAGE_SIZE ) ,
151 sort : "general. lastEnrolledDate:desc" ,
152 } ,
153 auth : { type : "jamf" } ,
154 } ,
155 ) ;
156 if ( response . status_code !== 200 ) {
157 fail (
158 `Jamf Pro returned ${ response . status_code } for the computer ` +
159 "inventory. Check that the Jamf connection's API client has the " +
160 "Read Computers privilege, then run the tool again. " ,
161 ) ;
162 }
163 const batch = readPage ( response . body , since ) ;
164 macs . push ( . . . batch . macs ) ;
165 done = batch . done ;
166 }
167 if ( macs . length === 0 ) {
168 return `No Macs enrolled in Jamf Pro in the last ${ params . hours } hours. ` ;
169 }
170
171 // **Look up each assigned user**
172 // Each assigned email should belong to an active person in the directory.
173 const people = new Map< string , Person > ( ) ;
174 for ( const email of assignedEmails ( macs ) ) {
175 const matches = await risotto . find_users ( { query : email } ) ;
176 people . set ( email , findPerson ( matches , email ) ) ;
177 }
178
179 // **Summarize the new Macs**
180 const flagged = macs . filter ( ( mac ) => problemsFor ( mac , people ) . length > 0 ) ;
181 const cutOff = done ? "" : ` Showing the newest ${ macs . length } only. ` ;
182 const summary = [
183 ` ${ plural ( macs . length , "Mac" ) } enrolled in Jamf Pro in the last ` +
184 ` ${ params . hours } hours; ${ flagged . length } need attention. ${ cutOff } ` ,
185 . . . macs . map ( ( mac ) => macLine ( mac , people ) ) ,
186 ] . join ( " \n " ) ;
187 if ( flagged . length === 0 || ! params . open_ticket_for_problems ) {
188 return summary ;
189 }
190
191 // **Open a ticket for Macs that need attention**
192 const ticket = await risotto . create_ticket ( {
193 title : ` ${ plural ( flagged . length , "new Mac" ) } in Jamf Pro need attention` ,
194 description : [
195 `These Macs enrolled in Jamf Pro in the last ${ params . hours } hours:` ,
196 . . . flagged . map ( ( mac ) => macLine ( mac , people ) ) ,
197 "Assign each one to an active person in Jamf Pro, turn on FileVault, " +
198 "and check that Jamf Pro manages it. " ,
199 ] . join ( " \n " ) ,
200 } ) ;
201 return ` ${ summary } \n Opened ticket ${ ticket . ticket_id } for them. ` ;
202 }
136 more lines 137 // **List recently enrolled Macs**
138 // Jamf Pro returns the newest enrollments first, so paging stops early.
139 const since = Date . now ( ) - params . hours * 60 * 60 * 1000 ;
140 const macs : NewMac [ ] = [ ] ;
141 let done = false ;
142 for ( let page = 0 ; page < MAX_PAGES && ! done ; page ++ ) {
143 // A literal URL, so Risotto checks it against your Jamf server on save.
144 // The sections are the only parts of each record this check reads.
145 const response = await http . get (
146 "https://acme. jamfcloud. com/api/v4/computers-inventory?section=GENERAL§ion=HARDWARE§ion=USER_AND_LOCATION§ion=DISK_ENCRYPTION" ,
147 {
148 query : {
149 page : String ( page ) ,
150 "page-size" : String ( PAGE_SIZE ) ,
151 sort : "general. lastEnrolledDate:desc" ,
152 } ,
153 auth : { type : "jamf" } ,
154 } ,
155 ) ;
156 if ( response . status_code !== 200 ) {
157 fail (
158 `Jamf Pro returned ${ response . status_code } for the computer ` +
159 "inventory. Check that the Jamf connection's API client has the " +
160 "Read Computers privilege, then run the tool again. " ,
161 ) ;
162 }
163 const batch = readPage ( response . body , since ) ;
164 macs . push ( . . . batch . macs ) ;
165 done = batch . done ;
166 }
167 if ( macs . length === 0 ) {
168 return `No Macs enrolled in Jamf Pro in the last ${ params . hours } hours. ` ;
169 }
33 more lines