├── .gitignore ├── LICENSE ├── README.md ├── basebuild.xml ├── build.xml ├── default.properties ├── src ├── bin │ ├── customhead.py │ ├── echo.py │ ├── runsearch.py │ └── search_command_example_app │ │ ├── __init__.py │ │ └── search_command.py ├── default │ ├── app.conf │ └── commands.conf └── metadata │ └── default.meta └── tests └── unit.py /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | 5 | # C extensions 6 | *.so 7 | 8 | # Distribution / packaging 9 | .Python 10 | env/ 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | *.egg-info/ 23 | .installed.cfg 24 | *.egg 25 | 26 | # PyInstaller 27 | # Usually these files are written by a python script from a template 28 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 29 | *.manifest 30 | *.spec 31 | 32 | # Installer logs 33 | pip-log.txt 34 | pip-delete-this-directory.txt 35 | 36 | # Unit test / coverage reports 37 | htmlcov/ 38 | .tox/ 39 | .coverage 40 | .coverage.* 41 | .cache 42 | nosetests.xml 43 | coverage.xml 44 | *,cover 45 | 46 | # Translations 47 | *.mo 48 | *.pot 49 | 50 | # Django stuff: 51 | *.log 52 | 53 | # Sphinx documentation 54 | docs/_build/ 55 | 56 | # PyBuilder 57 | target/ 58 | 59 | # VScode 60 | tasks.json 61 | 62 | # Custom build script stuff 63 | local.properties -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | 203 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Splunk Custom Search Command Example 2 | 3 | This repo contains an example of how to make a custom search command for Splunk. This includes a base class that makes it super easy to create one. 4 | 5 | Here is how you make one: 6 | 7 | ## Step 1: Copy search_command.py 8 | 9 | Copy the file search_command.py into the bin directory of your app. search_command.py is available within this repository under the path "/src/bin/search_command_example_app/search_command.py. 10 | 11 | When you are done copying it, your app should have a file with this path: 12 | 13 | bin/search_command.py 14 | 15 | ## Step 2: Create your custom search command 16 | 17 | In the steps below you will create the Python class that contains the code of your custom search command. 18 | 19 | ### 2.1: Create the custom search command file 20 | 21 | Create the Python file that will contain your custom search command. We are going to make a simple search command that just echoes something back, so it will be named "echo.py". This would be in the file: 22 | 23 | bin/echo.py 24 | 25 | ### 2.2: Import the search command base class 26 | 27 | Modify your search command to import the search command base class and sys: 28 | 29 | from search_command import SearchCommand 30 | import sys 31 | 32 | 33 | ### 2.3: Create your search command class 34 | 35 | Create an new class that inherits from the SearchCommand class and calls the constructor from the super-class. Note that I have named the class "Echo": 36 | 37 | class Echo(SearchCommand): 38 | 39 | def __init__(self): 40 | 41 | # Initialize the class 42 | SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command') 43 | 44 | def handle_results(self, results, session_key, in_preview): 45 | pass 46 | 47 | ### 2.4: Modify the constructor to take the search command arguments 48 | 49 | Modify the constructor to take whatever arguments you want it to take. In this case, I want the search command to take an argument "what_to_echo"; the constructor now takes the argument and stores it: 50 | 51 | from search_command import SearchCommand 52 | import sys 53 | 54 | class Echo(SearchCommand): 55 | 56 | def __init__(self, what_to_echo="Hello World"): 57 | 58 | # Save the parameters 59 | self.what_to_echo = what_to_echo 60 | 61 | # Initialize the class 62 | SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command') 63 | 64 | def handle_results(self, results, session_key, in_preview): 65 | pass 66 | 67 | ### 2.5: Implement handle_results() 68 | 69 | Implement handle_results() to do whatever your search command is supposed to do. In this, mine will just output the contents of the "what_to_echo" argument. 70 | 71 | 72 | from search_command import SearchCommand 73 | import sys 74 | 75 | class Echo(SearchCommand): 76 | 77 | def __init__(self, what_to_echo="Hello World"): 78 | 79 | # Save the parameters 80 | self.what_to_echo = what_to_echo 81 | 82 | # Initialize the class 83 | SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command') 84 | 85 | def handle_results(self, results, session_key, in_preview): 86 | self.output_results([{'echo' : self.what_to_echo}]) 87 | 88 | ### 2.5: Add the code to execute the search command 89 | 90 | Finally, add the code to cause the search command to execute at the bottom of the file: 91 | 92 | from search_command import SearchCommand 93 | import sys 94 | 95 | class Echo(SearchCommand): 96 | 97 | def __init__(self, what_to_echo="Hello World"): 98 | 99 | # Save the parameters 100 | self.what_to_echo = what_to_echo 101 | 102 | # Initialize the class 103 | SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command') 104 | 105 | def handle_results(self, results, session_key, in_preview): 106 | self.output_results([{'echo' : self.what_to_echo}]) 107 | 108 | if __name__ == '__main__': 109 | try: 110 | Echo.execute() 111 | sys.exit(0) 112 | except Exception as e: 113 | print e 114 | 115 | 116 | ## Step 3: Register your custom search command in commands.conf 117 | 118 | ### 3.1: Create the commands.conf entry 119 | 120 | Finally, register your search command by adding it to commands.conf. Create the file "default/commands.conf" in your app. The stanza name should match the name of the command as it will appear in Splunk; "filename" must match the filename of the search command in the bin directory: 121 | 122 | [echo] 123 | filename = echo.py 124 | generating = true 125 | passauth = false 126 | 127 | "generating" is set to true since this search command doesn't accept Splunk results but rather creates new results. "passauth" is set to false because this search command doesn't need to have access to splunkd. 128 | 129 | ### 3.2: Reload the commands.conf file 130 | 131 | Splunk won't recognize your new commands.conf entry until you restart or you specifically tell Splunk to reload the conf files. 132 | 133 | You can force Splunk to reload your commands.conf entry by vanigating to the followuing URL in your browser and clicking "refresh": 134 | 135 | http://127.0.0.1:8000/en-US/debug/refresh?entity=admin/commandsconf 136 | 137 | You don't need to call this endpoint everytime you edit the search command Python, just when you edit the commands.conf file. The Python code will get picked up automatically. 138 | 139 | ## Step 4: Run the command 140 | 141 | Now that Splunk recognizes your command, you can run it from the search bar. Run the search by entering this in the search bar: 142 | 143 | | echo what_to_echo="This works!" 144 | 145 | Make sure not to include spaces between the argument. Running a search like this will not work correctly: 146 | 147 | | echo what_to_echo = "This won't work" 148 | 149 | ## FAQs 150 | 151 | ### How do I consume search results in a search command? 152 | 153 | You will need to do two things if you need your search command to process results within SPL. 154 | 155 | One, update the command in commands.conf to set generating to false. 156 | 157 | Second, you will need to update handle_results() to do something with the results which will be in the "results" argument. Here is an example that adds a new field 'source_length' with the length of the source field: 158 | 159 | def handle_results(self, results, session_key, in_preview): 160 | 161 | for result in results: 162 | if 'source' in result: 163 | result['source_length'] = len(result['source']) 164 | 165 | self.output_results(results) 166 | 167 | ### How do I get a session key so that my search command can access Splunk's REST API? 168 | 169 | You will need to update your commands.conf entry to tell Splunk to pass a session key to your search command by setting "passauth" to true. Something like this: 170 | 171 | [echo] 172 | filename = echo.py 173 | passauth = true 174 | 175 | Once you do that, the session_key parameter that is passed to handle_results() will be a valid session key. 176 | -------------------------------------------------------------------------------- /basebuild.xml: -------------------------------------------------------------------------------- 1 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 126 | 127 | 128 | 132 | 133 | 134 | 135 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 152 | 153 | 154 | 155 | 156 | 157 | No app name was provided, cannot proceed 158 | 159 | 160 | 161 | 162 | 163 | ]]> 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | value.build.packageoutput.directory=tmp/packages 172 | value.build.optimize=true 173 | 174 | 175 | 176 | 177 | # Uncomment the file below and define the location of your Splunk installation in local.properties so that you 178 | # can deploy the application to a Splunk installation automatically: 179 | #value.deploy.splunk_home=C:/Program Files/Splunk 180 | 181 | # Change the following to match your install of Splunk if you want the build script to force Splunk to recognize new web-content automatically 182 | value.deploy.splunkd_url=https://127.0.0.1:8089 183 | value.deploy.splunkweb_url=http://127.0.0.1:8000 184 | value.deploy.splunk_username=admin 185 | value.deploy.splunk_password=changeme 186 | 187 | 188 | 189 | 190 | 191 | Success! 192 | 193 | A build script has been setup. To run your build run the following: 194 | 195 | ant 196 | 197 | Place the source-code of your app in the following "src" directory, a.k.a: 198 | 199 | ${absolute_src_path} 200 | 201 | You can customize the build process by placing properties in the default.properties file or the local.properties files. 202 | 203 | 204 | 205 | 208 | 209 | 210 | 211 | 212 | 213 | 217 | 218 | 222 | 223 | 227 | 228 | 232 | 233 | 234 | 235 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 253 | 254 | 255 | 258 | 259 | 260 | 261 | 262 | 265 | 266 | 267 | 271 | 272 | 273 | 274 | 275 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 299 | 300 | 301 | 302 | 303 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 330 | 331 | 332 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 351 | 352 | 353 | 354 | 355 | 356 | 357 | 358 | 359 | 360 | 361 | 362 | 363 | 364 | 365 | 366 | 367 | 368 | 369 | 370 | 371 | 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 390 | 391 | 392 | 393 | 394 | 395 | 396 | 397 | 398 | 399 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 417 | 418 | 419 | 420 | Revision number is: ${value.build.number} (${value.build.date}) 421 | 422 | 423 | 426 | 427 | 428 | 429 | 430 | 431 | 432 | 435 | 436 | 437 | 438 | 439 | 440 | 441 | 442 | 443 | 444 | 445 | 446 | 447 | 448 | 449 | 450 | 451 | 452 | 453 | 454 | 455 | 456 | 457 | 458 | 459 | 460 | 461 | 462 | 463 | 464 | 465 | 466 | 467 | 470 | 471 | 472 | 473 | 474 | 475 | 476 | 477 | 478 | 479 | 480 | 481 | 483 | 484 | 485 | 486 | 487 | 488 | 489 | 490 | 491 | 492 | 493 | 494 | 495 | 496 | 497 | 498 | 499 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 509 | 510 | 511 | 512 | 513 | 514 | 515 | 516 | 517 | 518 | 519 | 520 | 521 | 522 | 523 | 524 | 525 | 526 | 527 | 528 | 529 | 530 | 531 | 532 | 533 | 534 | 535 | 536 | 537 | 538 | 539 | 540 | 541 | 542 | 543 | 544 | 545 | 546 | 547 | 548 | 549 | 550 | 551 | 552 | 553 | 554 | 555 | 556 | 557 | 560 | 561 | 562 | 563 | 564 | 567 | 568 | 569 | 572 | 573 | 574 | 575 | 576 | 577 | 578 | 579 | 580 | 581 | 582 | 583 | 584 | 585 | 586 | 587 | 588 | 589 | 590 | 591 | 592 | 593 | 594 | 595 | 596 | 597 | 598 | App ${value.build.appname} build ${value.build.number} created: ${value.build.package.file} 599 | 600 | 601 | 602 | 605 | 606 | 607 | 608 | 609 | 610 | 611 | 612 | 613 | 614 | 615 | 618 | 619 | 1 620 | 621 | 622 | 625 | 626 | 627 | 628 | 629 | 632 | 633 | 634 | 635 | "value.deploy.splunk_home" has not been defined 636 | Declare it in the a local.properties file in the following path: 637 | 638 | ${absolute_src_path}/local.properties 639 | 640 | Below is an example of the entry in the file: 641 | 642 | value.deploy.splunk_home=/Applications/Splunk 643 | 644 | 645 | 646 | 649 | 650 | 651 | 652 | 653 | 654 | 655 | 656 | 657 | 658 | 659 | 662 | 663 | 664 | 665 | 666 | 667 | 668 | 669 | 670 | 671 | App ${value.build.appname} build ${value.build.number} deployed to ${export_dir} 672 | 673 | 674 | 677 | 678 | 679 | 680 | 681 | 682 | 683 | 684 | 687 | 688 | 689 | 690 | [settings] 691 | minify_js = False 692 | minify_css = False 693 | js_no_cache = True 694 | cacheEntriesLimit = 0 695 | cacheBytesLimit = 0 696 | enableWebDebug = True 697 | 698 | 699 | 700 | 703 | 704 | SPLUNK_FIPS=1 705 | 706 | 707 | 710 | 711 | 712 | 713 | [settings] 714 | root_endpoint=/custom_endpoint 715 | 716 | 717 | 718 | 721 | 722 | 723 | 724 | 725 | 726 | 727 | 730 | 731 | 732 | 733 | 734 | 735 | 736 | 737 | 738 | 739 | 740 | 741 | 742 | 743 | 746 | 747 | 748 | 749 | 750 | 751 | 752 | 753 | 754 | 755 | 756 | 757 | 758 | 759 | 762 | 763 | 764 | 765 | 766 | 769 | 770 | 771 | 772 | 773 | 774 | 775 | 776 | 779 | 780 | 781 | 782 | "splunkd_url" has not been defined 783 | Declare it in the a local.properties file in the following path: 784 | 785 | ${absolute_src_path}/local.properties 786 | 787 | Below is an example of the entry in the file: 788 | 789 | value.deploy.splunkd_url=http://splunk.example.com:8000 790 | 791 | 792 | 793 | 796 | 797 | 798 | 799 | "splunkweb_url" has not been defined 800 | Declare it in the a local.properties file in the following path: 801 | 802 | ${absolute_src_path}/local.properties 803 | 804 | Below is an example of the entry in the file: 805 | 806 | value.deploy.splunkweb_url=https://splunk.example.com:8089 807 | 808 | 809 | 810 | 813 | 814 | 815 | 816 | 817 | 818 | 819 | 820 | 821 | 822 | 823 | 824 | 825 | 826 | 827 | 828 | 829 | 830 | 831 | 832 | 835 | 836 | 837 | 838 | 839 | 840 | 841 | 844 | 845 | 846 | 847 | 848 | 849 | 850 | 851 | 852 | 853 | 856 | 857 | 858 | 859 | 860 | 861 | 862 | 863 | 864 | 865 | 866 | 869 | 870 | 871 | 874 | 875 | 876 | 879 | 880 | 881 | 884 | 885 | 886 | 887 | 888 | 889 | 890 | 891 | 892 | 893 | 894 | 895 | 896 | 897 | 898 | 899 | 900 | 903 | 904 | 905 | 906 | 907 | 908 | 909 | 910 | 911 | 912 | 913 | 914 | 915 | 916 | 917 | 920 | 921 | 922 | 923 | 924 | 925 | 926 | 927 | 928 | 933 | 934 | 935 | 936 | 937 | 938 | 939 | 940 | 941 | 942 | 943 | 944 | 945 | 946 | 947 | 953 | 954 | 955 | 956 | 960 | 961 | 962 | 963 | 964 | 965 | 966 | 967 | 968 | 969 | 970 | 971 | 972 | 973 | 974 | 975 | 976 | 977 | 978 | 979 | 980 | 981 | 982 | 983 | 984 | 987 | 988 | 989 | 990 | 991 | 994 | 995 | 996 | 999 | 1000 | 1001 | 1002 | 1003 | 1004 | 1005 | 1006 | 1007 | 1008 | 1009 | 1010 | 1011 | 1012 | 1013 | 1014 | 1015 | 1016 | 1017 | 1020 | 1021 | 1022 | 1023 | 1024 | 1025 | 1026 | 1029 | 1030 | 1031 | 1034 | 1035 | 1036 | 1037 | 1038 | 1039 | 1040 | 1041 | 1042 | 1043 | 1044 | 1045 | 1046 | 1047 | 1050 | 1051 | 1052 | 1055 | 1056 | 1057 | 1060 | 1061 | 1062 | 1065 | 1066 | 1067 | 1070 | 1071 | 1072 | 1073 | 1074 | 1075 | 1076 | 1077 | 1078 | 1079 | 1080 | 1081 | 1082 | 1083 | 1086 | 1087 | 1088 | 1089 | 1092 | 1093 | 1094 | 1095 | 1096 | 1097 | 1098 | 1099 | 1100 | 1101 | 1102 | 1105 | 1106 | 1107 | 1108 | 1109 | 1110 | 1111 | 1112 | 1113 | 1114 | 1115 | 1116 | 1119 | 1120 | 1121 | 1124 | 1125 | 1126 | 1127 | 1128 | 1129 | 1130 | 1131 | 1132 | 1133 | 1134 | 1135 | 1136 | 1137 | 1138 | 1139 | 1140 | appinspect was not found. 1141 | Install appinspect from http://dev.splunk.com/view/appinspect/SP-CAAAFAK if you haven't already. 1142 | 1143 | You can declare the "value.test.appinspect_path" parameter with the path where appinspect is installed if isn't on your system path. 1144 | Declare it in a local.properties file in the following path: 1145 | ${absolute_src_path}/local.properties 1146 | 1147 | 1148 | 1149 | 1150 | 1151 | -------------------------------------------------------------------------------- /build.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 7 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /default.properties: -------------------------------------------------------------------------------- 1 | value.build.packageoutput.directory=tmp/packages 2 | value.build.workingcopy.directory=. 3 | 4 | # Define the location of your Splunk installation in local.properties so that you can deploy the application 5 | # to a Splunk installation automatically: 6 | #value.deploy.splunk_home=C:/Program Files/Splunk 7 | -------------------------------------------------------------------------------- /src/bin/customhead.py: -------------------------------------------------------------------------------- 1 | from search_command_example_app.search_command import SearchCommand 2 | 3 | class CustomHead(SearchCommand): 4 | 5 | def __init__(self, count=1): 6 | 7 | # Save the parameters 8 | self.count = int(count) 9 | 10 | # Initialize the class 11 | SearchCommand.__init__( self, run_in_preview=True, logger_name='customhead_search_command') 12 | 13 | def handle_results(self, results, session_key, in_preview): 14 | results_to_output = [] 15 | 16 | # Cut the output to only the number we want to send 17 | results = results[:self.count] 18 | 19 | self.logger.info("%r", dir(results[0])) 20 | #for result in results: 21 | # results_to_output 22 | self.output_results(results) 23 | 24 | if __name__ == '__main__': 25 | CustomHead.execute() 26 | -------------------------------------------------------------------------------- /src/bin/echo.py: -------------------------------------------------------------------------------- 1 | from search_command_example_app.search_command import SearchCommand 2 | 3 | class Echo(SearchCommand): 4 | 5 | def __init__(self, what_to_echo="Hello World"): 6 | 7 | # Save the parameters 8 | self.what_to_echo = what_to_echo 9 | 10 | # Initialize the class 11 | SearchCommand.__init__( self, run_in_preview=True, logger_name='echo_search_command') 12 | 13 | def handle_results(self, results, session_key, in_preview): 14 | self.output_results([{'echo' : self.what_to_echo}]) 15 | 16 | if __name__ == '__main__': 17 | Echo.execute() -------------------------------------------------------------------------------- /src/bin/runsearch.py: -------------------------------------------------------------------------------- 1 | 2 | import time 3 | 4 | import splunk.rest 5 | import splunk.search 6 | 7 | from search_command_example_app.search_command import SearchCommand 8 | 9 | class RunSearch(SearchCommand): 10 | 11 | def __init__(self, search_name=None): 12 | 13 | # Save the parameters 14 | self.search_name = search_name 15 | 16 | # Initialize the class 17 | SearchCommand.__init__(self, run_in_preview=True, logger_name='runsearch_search_command') 18 | 19 | def handle_results(self, results, session_key, in_preview): 20 | 21 | # Dispatch the search 22 | job = splunk.search.dispatchSavedSearch(self.search_name, session_key) 23 | 24 | # Wait until the job is done 25 | while not job.isDone: 26 | time.sleep(1) 27 | 28 | # Get the results 29 | dataset = job.results 30 | 31 | # Prep the output 32 | events = [] 33 | for event in dataset: 34 | events.append(event) 35 | 36 | # Output the results 37 | self.output_results(events) 38 | 39 | if __name__ == '__main__': 40 | RunSearch.execute() 41 | -------------------------------------------------------------------------------- /src/bin/search_command_example_app/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/LukeMurphey/splunk-search-command-example/2525f76ca11c9777b591bc6594a68f137a795c8a/src/bin/search_command_example_app/__init__.py -------------------------------------------------------------------------------- /src/bin/search_command_example_app/search_command.py: -------------------------------------------------------------------------------- 1 | """ 2 | This class provides a base class for search commands that handles much of the Splunk-to-Python 3 | interaction necessary for making a search command. 4 | 5 | This is licensed under the Apache License Version 2.0 6 | See https://www.apache.org/licenses/LICENSE-2.0.html 7 | 8 | To make a search command, you will need to: 9 | 1) Sub-class the search command (see below for an example) 10 | 2) Declare your search command in commands.conf 11 | 12 | See below for a basic example of a class that sub-classes SearchCommand: 13 | 14 | 15 | 16 | from search_command import SearchCommand 17 | import sys 18 | 19 | class Echo(SearchCommand): 20 | 21 | def __init__(self, what_to_echo="Hello World"): 22 | 23 | # Save the parameters 24 | self.what_to_echo = what_to_echo 25 | 26 | # Initialize the class 27 | SearchCommand.__init__( self, run_in_preview=True, logger_name='echo_search_command') 28 | 29 | def handle_results(self, results, session_key, in_preview): 30 | self.output_results([{'echo' : self.what_to_echo}]) 31 | 32 | if __name__ == '__main__': 33 | try: 34 | Echo.execute() 35 | sys.exit(0) 36 | except Exception as e: 37 | print e 38 | """ 39 | 40 | import splunk.Intersplunk 41 | import sys 42 | import splunk 43 | import json 44 | import logging 45 | from logging import handlers 46 | 47 | from splunk.appserver.mrsparkle.lib.util import make_splunkhome_path 48 | 49 | class SearchCommand(object): 50 | """ 51 | A base class for implementing a search command. 52 | """ 53 | 54 | # List of valid parameters 55 | PARAM_RUN_IN_PREVIEW = "run_in_preview" 56 | PARAM_DEBUG = "debug" 57 | 58 | VALID_PARAMS = [PARAM_RUN_IN_PREVIEW, PARAM_DEBUG] 59 | 60 | def __init__(self, run_in_preview=False, logger_name='python_search_command', log_level=logging.INFO, run_only_in_preview=False): 61 | """ 62 | Constructs an instance of the search command. 63 | 64 | Arguments: 65 | run_in_preview -- Indicates whether the search command should run in preview mode 66 | logger_name -- The logger name to append to the logger 67 | log_level -- The log level to use for the logger 68 | run_only_in_preview -- Run the command only in preview 69 | """ 70 | 71 | self.run_in_preview = run_in_preview 72 | self.run_only_in_preview = run_only_in_preview 73 | 74 | # Check and save the logger name 75 | self._logger = None 76 | 77 | if logger_name is None or len(logger_name) == 0: 78 | raise Exception("Logger name cannot be empty") 79 | 80 | self.logger_name = logger_name 81 | self.log_level = log_level 82 | 83 | # The session key will be cached here once the search command is called 84 | self.session_key = None 85 | 86 | @property 87 | def logger(self): 88 | """ 89 | A property that returns the logger. 90 | """ 91 | 92 | # Make a logger unless it already exists 93 | if self._logger is not None: 94 | return self._logger 95 | 96 | logger = logging.getLogger(self.logger_name) 97 | 98 | # Prevent the log messages from being duplicated in the python.log file: 99 | logger.propagate = False 100 | logger.setLevel(self.log_level) 101 | 102 | file_handler = handlers.RotatingFileHandler(make_splunkhome_path(['var', 'log', 'splunk', self.logger_name + '.log']), maxBytes=25000000, backupCount=5) 103 | formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s') 104 | file_handler.setFormatter(formatter) 105 | 106 | logger.addHandler(file_handler) 107 | 108 | self._logger = logger 109 | return self._logger 110 | 111 | @logger.setter 112 | def logger(self, logger): 113 | self._logger = logger 114 | 115 | def has_capability(self, capability): 116 | """ 117 | Determine if the user has the given capability. This will return true if any of the 118 | following are true: 119 | 120 | 1) The user has the given capability 121 | 2) The user has 'admin_all_objects' 122 | 3) The Splunk install is using the free license 123 | """ 124 | 125 | try: 126 | capabilities = self.get_capabilities() 127 | 128 | if capability in capabilities or 'admin_all_objects' in capabilities: 129 | return True 130 | 131 | except splunk.LicenseRestriction: 132 | # This can happen when the Splunk install is using the free license 133 | 134 | # Check to see if the Splunk install is using the free license and allow access if so 135 | # We are only going to check for this if it is the admin user since that is the user 136 | # that the non-authenticated user is logged in as when the free license is used. 137 | if self.is_using_free_licence(): 138 | return True 139 | 140 | return False 141 | 142 | return False 143 | 144 | def get_capabilities(self): 145 | """ 146 | Get the users' assigned capabilities. 147 | """ 148 | return self.get_user_context().get('capabilities', None) 149 | 150 | def get_user_context(self): 151 | """ 152 | Get the users' context. 153 | """ 154 | 155 | response, content = splunk.rest.simpleRequest('/services/authentication/current-context?output_mode=json', 156 | sessionKey=self.session_key) 157 | 158 | if response.status == 200: 159 | 160 | # Parse the JSON content 161 | user_info = json.loads(content) 162 | 163 | return user_info['entry'][0]['content'] 164 | 165 | return None 166 | 167 | def is_using_free_licence(self): 168 | """ 169 | Determine if the Splunk install is using the free license 170 | """ 171 | 172 | # See the free license is active 173 | response, content = splunk.rest.simpleRequest('/services/licenser/groups/Free?output_mode=json', 174 | sessionKey=self.session_key) 175 | 176 | # If the response didn't return a 200 code, then the entry likely didn't exist and 177 | # the host is not using the free license 178 | if response.status == 200: 179 | 180 | # Parse the JSON content 181 | license_info = json.loads(content) 182 | 183 | if license_info['entry'][0]['content']['is_active'] == 1: 184 | # This host is using the free license, allow this through 185 | return True 186 | 187 | # Apparently the free licence is not in use 188 | return False 189 | 190 | return False 191 | 192 | @classmethod 193 | def parse_argument(cls, argument): 194 | """ 195 | Parses an argument in the form of name=value and returns the name and value as two arguments 196 | 197 | Arguments: 198 | argument -- The argument that should be split into a name/value pair (i.e. name=value) 199 | """ 200 | 201 | # Find the character that splits the name from the value (returns -1 if it cannot be found) 202 | splitter = argument.find('=') 203 | 204 | # If no equal-sign was found then initialize the value to None 205 | if splitter < 0: 206 | name = None 207 | value = argument 208 | 209 | # If a splitter was found, then parse the value 210 | else: 211 | name = argument[0:splitter] 212 | value = argument[splitter+1:len(argument)] 213 | 214 | # Return the results 215 | return name, value 216 | 217 | @classmethod 218 | def get_arguments(cls): 219 | """ 220 | Get the arguments as args and kwargs so that they can be processed into a constructor call 221 | to a search command. 222 | """ 223 | 224 | kwargs = {} 225 | args = [] 226 | 227 | # Iterate through the arguments and initialize the corresponding argument 228 | if len(sys.argv) > 1: 229 | 230 | # Iterate through each argument 231 | for argument in sys.argv[1:]: 232 | 233 | # Parse the argument 234 | name, value = cls.parse_argument(argument) 235 | 236 | # If the argument has no value then it was an unnamed argument. Put it in the 237 | # arguments array 238 | if name is None: 239 | args.append(value) 240 | 241 | else: 242 | # Put the argument in a dictionary 243 | kwargs[name] = value 244 | 245 | return args, kwargs 246 | 247 | @classmethod 248 | def make_instance(cls): 249 | """ 250 | Produce an instance of the search command with arguments from the command-line. 251 | """ 252 | 253 | args, kwargs = cls.get_arguments() 254 | return cls(*args, **kwargs) 255 | 256 | @classmethod 257 | def execute(cls): 258 | """ 259 | Initialize an instance and run it. 260 | """ 261 | 262 | try: 263 | 264 | instance = cls.make_instance() 265 | instance.run() 266 | 267 | except Exception as exception: 268 | splunk.Intersplunk.parseError(str(exception)) 269 | # self.logger.exception("Search command threw an exception") 270 | 271 | def run(self, results=None): 272 | """ 273 | Run the search command. 274 | """ 275 | 276 | try: 277 | 278 | # Get the results from Splunk (unless results were provided) 279 | if results is None: 280 | results, dummyresults, settings = splunk.Intersplunk.getOrganizedResults() 281 | self.session_key = settings.get('sessionKey', None) 282 | 283 | # Don't write out the events in preview mode 284 | in_preview = settings.get('preview', '0') in [1, '1'] 285 | 286 | # If run_in_preview is undefined, then just continue 287 | if self.run_in_preview is None: 288 | pass 289 | 290 | # Don't do anything if the command is supposed to run only in preview but the 291 | # results are not preview results 292 | elif self.run_only_in_preview and not in_preview: 293 | 294 | # Don't run in non-preview mode since we already processed the events in 295 | # preview mode 296 | if len(results) > 0: 297 | self.logger.info( "Search command is set to run only in preview, ignoring %d results provided in non-preview mode" % (len(results))) 298 | 299 | return None 300 | 301 | # Don't do anything if the command is NOT supposed to run in preview but the 302 | # results are previewed results 303 | elif not self.run_in_preview and in_preview: 304 | return None 305 | 306 | else: 307 | settings = None 308 | 309 | # Execute the search command 310 | self.handle_results(results, self.session_key, in_preview) 311 | 312 | except Exception as exception: 313 | splunk.Intersplunk.parseError(str(exception)) 314 | self.logger.exception("Search command threw an exception") 315 | 316 | def output_results(self, results): 317 | """ 318 | Output results to Splunk. 319 | 320 | Arguments: 321 | results -- An array of dictionaries of fields/values to send to Splunk. 322 | """ 323 | 324 | splunk.Intersplunk.outputResults(results) 325 | 326 | def handle_results(self, results, session_key, in_preview): 327 | """ 328 | This function needs to be overridden. 329 | 330 | Arguments: 331 | results -- The results from Splunk to process 332 | session_key -- The session key to use for connecting to Splunk 333 | in_preview -- Whether the search is running in preview 334 | """ 335 | 336 | raise Exception("handle_results needs to be implemented") -------------------------------------------------------------------------------- /src/default/app.conf: -------------------------------------------------------------------------------- 1 | [launcher] 2 | version = 0.5 3 | description = An example of writing a search command 4 | author = LukeMurphey 5 | 6 | [package] 7 | id = search_command_example 8 | 9 | [install] 10 | build = ${value.build.number} 11 | # Last commit: ${value.build.date} 12 | is_configured = false 13 | 14 | [ui] 15 | is_visible = false 16 | label = Search Command Example -------------------------------------------------------------------------------- /src/default/commands.conf: -------------------------------------------------------------------------------- 1 | ## Usage: | echo what_to_echo="Hello world!" 2 | ## Purpose: an example of writing a search command 3 | [echo] 4 | filename = echo.py 5 | generating = true 6 | passauth = false 7 | 8 | ## Usage: | customhead count=10 9 | ## Purpose: an example of a search command that processes results 10 | [customhead] 11 | filename = customhead.py 12 | generating = false 13 | passauth = false 14 | 15 | 16 | ## Usage: | runsearch search_name="TestSearch" 17 | ## Purpose: an example of a search command that runs a search 18 | [runsearch] 19 | filename = runsearch.py 20 | generating = true 21 | passauth = true -------------------------------------------------------------------------------- /src/metadata/default.meta: -------------------------------------------------------------------------------- 1 | [] 2 | access = read : [ * ], write : [ admin ] 3 | export = system -------------------------------------------------------------------------------- /tests/unit.py: -------------------------------------------------------------------------------- 1 | 2 | import unittest 3 | import errno 4 | import sys 5 | import os 6 | import re 7 | 8 | sys.path.append( os.path.join("..", "src", "bin") ) 9 | sys.path.append( os.path.join("..", "src", "bin", "search_command_example_app") ) 10 | 11 | from search_command_example_app.search_command import SearchCommand 12 | 13 | class TestSearchCommand(unittest.TestCase): 14 | """ 15 | Test the ability to construct the search command. 16 | """ 17 | 18 | def test_construct(self): 19 | """ 20 | Make sure the search command can be constructed. 21 | """ 22 | search_command = SearchCommand() 23 | self.assertIsNotNone(search_command) 24 | 25 | if __name__ == "__main__": 26 | unittest.main() 27 | --------------------------------------------------------------------------------